@deepseek-ai/dsh-session 0.1.3-alpha.2 → 0.1.5-alpha.1

package/lib/index.js

@@ -53,7 +53,85 @@ function SessionLogOffset(value) {
 * immutable prior-generation, and current fast-path rules are recorded in
 * `.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md`.
 */
-const SESSION_FORMAT_VERSION = 2;
+const SESSION_FORMAT_VERSION = 3;
+//#endregion
+//#region lib/types/known-event-types.js
+/**
+* GENERATED by `scripts/gen-persistence-catalog.ts` — do not edit by hand; run
+* `pnpm run gen-persistence-catalog` to regenerate (verified fresh by
+* `pnpm run verify-persistence-catalog`, part of `doc-sync`).
+* @module @deepseek-ai/dsh-session/known-event-types
+*/
+/**
+* Every `SessionEventMap` member declared in this repository — the event
+* vocabulary this build understands. The persistence read path refuses to
+* interpret a log containing a type outside this set unless the event
+* carries the envelope's `ignorable` marker (see `SessionEvent.ignorable`
+* in `./types.ts`): such a log was likely written by a newer harness, and
+* silently skipping a required event would reconstruct a wrong session.
+* Downstream (out-of-repo) plugin events are outside this list by
+* construction. The persisted `SessionEvent.ignorable` marker is the
+* compatibility mechanism; event-name registration was rejected because
+* it does not classify omission safety and would make reads
+* composition-dependent. The rationale is in
+* `.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md`.
+*/
+const KNOWN_SESSION_EVENT_TYPES = new Set([
+	"agent-preset/selected",
+	"agent/inbox/spliced",
+	"approval/asked",
+	"approval/decided",
+	"approval/policy",
+	"assistant/attempt",
+	"assistant/message",
+	"command/done",
+	"command/run",
+	"compaction/end",
+	"compaction/prune",
+	"compaction/start",
+	"compaction/summary",
+	"feedback/message-delete",
+	"feedback/message-put",
+	"feedback/record",
+	"goal/change",
+	"hook/invoked",
+	"hook/result",
+	"llm/retry",
+	"llm/retry-started",
+	"model/selection",
+	"permission/preset",
+	"plan/mode",
+	"request/context",
+	"request/header",
+	"sandbox/mode",
+	"schedule/change",
+	"session-log-deepseek/delivery-accepted",
+	"session/end-seed",
+	"session/title",
+	"session/title-llm-request",
+	"step/end",
+	"step/start",
+	"subagent/descriptor",
+	"subagent/model-selection-policy",
+	"system/message",
+	"team/member",
+	"team/message/delivered",
+	"team/message/queued",
+	"team/task",
+	"todo/write",
+	"tool-workflow/agent-end",
+	"tool-workflow/agent-start",
+	"tool-workflow/run-end",
+	"tool-workflow/run-start",
+	"tool/call",
+	"tool/ptc-dispatch",
+	"tool/ptc-dispatch-start",
+	"tool/result",
+	"turn/end",
+	"turn/start",
+	"user/message",
+	"web/deepseek-search-llm-request"
+]);
 //#endregion
 //#region lib/types/surface.js
 /**
@@ -67,6 +145,7 @@ const SESSION_FORMAT_VERSION = 2;
 */
 /** Runtime counterpart of the message-producing event union. */
 const SURFACE_EVENT_TYPES = new Set([
+	"system/message",
 	"user/message",
 	"assistant/message",
 	"tool/result"
@@ -74,7 +153,7 @@ const SURFACE_EVENT_TYPES = new Set([
 /**
 * Whether an event type can join the model-visible surface.
 * @param type - event type to test.
-* @returns true for one of the three message-producing event types.
+* @returns true for one of the four message-producing event types.
 */
 function isSurfaceEligibleType(type) {
 	return SURFACE_EVENT_TYPES.has(type);
@@ -128,6 +207,7 @@ function isReplacementSurfaceEvent(event) {
 function deriveEventMessage(event) {
 	switch (event.type) {
 		case "user/message": return event.data;
+		case "system/message":
 		case "assistant/message":
 			if (event.data.message.content.length === 0) return null;
 			return event.data.message;
@@ -135,6 +215,36 @@ function deriveEventMessage(event) {
 		default: return null;
 	}
 }
+/** Whether a payload field is a JSON object rather than an array or scalar. */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Reject noncanonical request-header fields and contradictory tool failure metadata.
+* This does not validate complete event payloads or embedded provider streams.
+* @param event - event whose locally related payload fields are inspected.
+* @param subject - event location to include in validation errors.
+* @throws when request data/header is not an object, optional header fields are empty, or tool failure metadata contradicts its message.
+*/
+function validateSessionEventData(event, subject) {
+	const data = event.data;
+	if (event.type === "request/header") {
+		if (!isRecord(data)) throw new Error(`${subject} data must be an object`);
+		const header = data["header"];
+		if (!isRecord(header)) throw new Error(`${subject} header must be an object`);
+		if (Object.hasOwn(header, "system")) throw new Error(`${subject} must omit header.system; use system/message`);
+		if (Array.isArray(header["tools"]) && header["tools"].length === 0) throw new Error(`${subject} must omit empty tools`);
+		const defaults = header["adapterDefaults"];
+		if (isRecord(defaults) && Object.keys(defaults).length === 0) throw new Error(`${subject} must omit empty adapterDefaults`);
+	} else if (event.type === "tool/result") {
+		if (!isRecord(data)) throw new Error(`${subject} data must be an object`);
+		if (data["error"] === void 0) return;
+		const message = data["message"];
+		const content = isRecord(message) ? message["content"] : void 0;
+		const block = Array.isArray(content) ? content[0] : void 0;
+		if (!isRecord(block) || block["isError"] !== true) throw new Error(`${subject} error requires message content[0].isError === true`);
+	}
+}
 /** Create an empty surface fold state. */
 function createFoldState() {
 	return {
@@ -149,12 +259,13 @@ function isEventSeq(value) {
 /** Whether a runtime value is the exact positional-replacement shape. */
 function isReplaceOp(value) {
 	const op = value;
-	return Object.keys(op).length === 3 && Object.hasOwn(op, "op") && Object.hasOwn(op, "start") && Object.hasOwn(op, "end") && op["op"] === "replace" && isEventSeq(op["start"]) && isEventSeq(op["end"]);
+	return Object.keys(op).length === 3 && Object.hasOwn(op, "op") && Object.hasOwn(op, "startSeq") && Object.hasOwn(op, "endSeq") && op["op"] === "replace" && isEventSeq(op["startSeq"]) && isEventSeq(op["endSeq"]);
 }
 /** Validate event-local surface eligibility and return its operation. */
 function surfaceOpOf(event) {
 	const raw = event;
 	if (!isSurfaceEligibleType(event.type)) {
+		if (!KNOWN_SESSION_EVENT_TYPES.has(event.type) && event.ignorable === true) return;
 		if (raw.surfaceOp !== void 0) throw new Error(`session event "${event.type}" is not surface-eligible and cannot carry surfaceOp`);
 		if (raw.sourceEventSeqs !== void 0) throw new Error(`session event "${event.type}" is not surface-eligible and cannot carry sourceEventSeqs`);
 		return;
@@ -186,13 +297,26 @@ function assertProvenance(event, shadowedSeqs) {
 	const missing = shadowedSeqs.filter((seq) => !sources.has(seq));
 	if (missing.length > 0) throw new Error(`surface replace: sourceEventSeqs must include every shadowed surface node; missing ${missing.join(", ")}`);
 }
+/**
+* Validate one event's surface metadata without checking membership in a log or surface.
+* @param event - event whose marker and source sequence values are inspected.
+* Unknown ignorable records retain opaque metadata and never change the surface.
+* @returns the validated operation, or undefined for a log-only or unknown ignorable event.
+* @throws when metadata violates event-local eligibility, marker, or source-sequence rules.
+*/
+function validateSurfaceMetadata(event) {
+	const op = surfaceOpOf(event);
+	if (op !== void 0 && op !== "append" && (op.startSeq >= event.seq || op.endSeq >= event.seq)) throw new Error(`surface replace at seq ${event.seq}: startSeq and endSeq must reference earlier events`);
+	if (op !== void 0) assertProvenance(event, []);
+	return op;
+}
 /** Locate one replacement range without mutating the current fold state. */
 function replacementRange(state, op) {
-	const startIdx = state.nodes.indexOf(op.start);
-	if (startIdx === -1) throw new Error(`surface replace: start seq ${op.start} not found in surface`);
-	const endIdx = state.nodes.indexOf(op.end);
-	if (endIdx === -1) throw new Error(`surface replace: end seq ${op.end} not found in surface`);
-	if (startIdx > endIdx) throw new Error(`surface replace: start seq ${op.start} (index ${startIdx}) is after end seq ${op.end} (index ${endIdx})`);
+	const startIdx = state.nodes.indexOf(op.startSeq);
+	if (startIdx === -1) throw new Error(`surface replace: start seq ${op.startSeq} not found in surface`);
+	const endIdx = state.nodes.indexOf(op.endSeq);
+	if (endIdx === -1) throw new Error(`surface replace: end seq ${op.endSeq} not found in surface`);
+	if (startIdx > endIdx) throw new Error(`surface replace: start seq ${op.startSeq} (index ${startIdx}) is after end seq ${op.endSeq} (index ${endIdx})`);
 	return {
 		startIdx,
 		endIdx,
@@ -244,26 +368,35 @@ function assertToolResultRewrite(event, shadowedSeqs, events, baseSeq) {
 		if (!isDeepEqualJson(originalRest, replacementRest)) throw new Error("tool/result surface replacement may change only content");
 	}
 }
+/**
+* Protect the system prompt at surface node 0. A replacement covering node 0
+* while that node is a `system/message` must itself be a `system/message` over
+* exactly that node; later system nodes carry no protection and a compaction
+* range may shadow them.
+*/
+function assertSystemHeadRewrite(event, state, startIdx, shadowedSeqs, events, baseSeq) {
+	if (startIdx !== 0) return;
+	if (events[state.nodes[0] - baseSeq]?.type !== "system/message") return;
+	if (event.type !== "system/message" || shadowedSeqs.length !== 1) throw new Error("surface replace: node 0 holds the system prompt and may be rewritten only by a system/message over exactly that node");
+}
 /** Validate one event at its replay boundary and prepare its atomic fold transition. */
 function planSurfaceEvent(state, event, expectedSeq, events, baseSeq) {
 	if (event.seq !== expectedSeq) throw new Error(`session event seq ${event.seq} is not contiguous; expected ${expectedSeq}`);
-	const surfaceOp = surfaceOpOf(event);
+	const surfaceOp = validateSurfaceMetadata(event);
 	if (surfaceOp === void 0) return;
-	if (surfaceOp === "append") {
-		assertProvenance(event, []);
-		return {
-			kind: "append",
-			seq: event.seq
-		};
-	}
+	if (surfaceOp === "append") return {
+		kind: "append",
+		seq: event.seq
+	};
 	const range = replacementRange(state, surfaceOp);
 	assertProvenance(event, range.shadowedSeqs);
 	assertToolResultRewrite(event, range.shadowedSeqs, events, baseSeq);
+	assertSystemHeadRewrite(event, state, range.startIdx, range.shadowedSeqs, events, baseSeq);
 	return {
 		kind: "replace",
 		seq: event.seq,
-		start: surfaceOp.start,
-		end: surfaceOp.end,
+		start: surfaceOp.startSeq,
+		end: surfaceOp.endSeq,
 		...range
 	};
 }
@@ -371,9 +504,9 @@ var SurfaceManager = class {
 * @module dsh-session/request-header
 */
 /**
-* Normalize a header to canonical form: an empty system prompt and empty tool
-* list become absent fields, matching how requests are built. Logging, folding,
-* and comparison use this one representation.
+* Normalize a header to canonical form: an empty tool list becomes an absent
+* field, matching how requests are built. Logging, folding, and comparison use
+* this one representation.
 * @param header - the header to normalize (not mutated).
 * @returns the canonical header.
 */
@@ -382,7 +515,6 @@ function canonicalHeader(header) {
 	return {
 		config: header.config,
 		...adapterDefaults?.reasoningEffort === true || adapterDefaults?.maxTokens === true ? { adapterDefaults } : {},
-		...header.system !== void 0 && header.system.length > 0 ? { system: header.system } : {},
 		...header.tools !== void 0 && header.tools.length > 0 ? { tools: header.tools } : {}
 	};
 }
@@ -394,10 +526,10 @@ function sameSchema(a, b) {
 * Field-wise equality over canonical headers. Tool schemas compare in order.
 * @param a - one canonical header.
 * @param b - the other.
-* @returns whether config, system, and tools all match.
+* @returns whether config, adapter defaults, and tools all match.
 */
 function headerEquals(a, b) {
-	if (!callConfigEquals(a.config, b.config) || a.adapterDefaults?.reasoningEffort !== b.adapterDefaults?.reasoningEffort || a.adapterDefaults?.maxTokens !== b.adapterDefaults?.maxTokens || a.system !== b.system) return false;
+	if (!callConfigEquals(a.config, b.config) || a.adapterDefaults?.reasoningEffort !== b.adapterDefaults?.reasoningEffort || a.adapterDefaults?.maxTokens !== b.adapterDefaults?.maxTokens) return false;
 	const at = a.tools ?? [];
 	const bt = b.tools ?? [];
 	return at.length === bt.length && at.every((tool, i) => sameSchema(tool, bt[i]));
@@ -575,83 +707,6 @@ function interruptedTurnClosers(events) {
 	return closers;
 }
 //#endregion
-//#region lib/types/known-event-types.js
-/**
-* GENERATED by `scripts/gen-persistence-catalog.ts` — do not edit by hand; run
-* `pnpm run gen-persistence-catalog` to regenerate (verified fresh by
-* `pnpm run verify-persistence-catalog`, part of `doc-sync`).
-* @module @deepseek-ai/dsh-session/known-event-types
-*/
-/**
-* Every `SessionEventMap` member declared in this repository — the event
-* vocabulary this build understands. The persistence read path refuses to
-* interpret a log containing a type outside this set unless the event
-* carries the envelope's `ignorable` marker (see `SessionEvent.ignorable`
-* in `./types.ts`): such a log was likely written by a newer harness, and
-* silently skipping a required event would reconstruct a wrong session.
-* Downstream (out-of-repo) plugin events are outside this list by
-* construction. The persisted `SessionEvent.ignorable` marker is the
-* compatibility mechanism; event-name registration was rejected because
-* it does not classify omission safety and would make reads
-* composition-dependent. The rationale is in
-* `.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md`.
-*/
-const KNOWN_SESSION_EVENT_TYPES = new Set([
-	"agent-preset/selected",
-	"agent/inbox/spliced",
-	"approval/asked",
-	"approval/decided",
-	"approval/policy",
-	"assistant/attempt",
-	"assistant/message",
-	"command/done",
-	"command/run",
-	"compaction/end",
-	"compaction/prune",
-	"compaction/start",
-	"compaction/summary",
-	"feedback/message-delete",
-	"feedback/message-put",
-	"feedback/record",
-	"goal/change",
-	"hook/invoked",
-	"hook/result",
-	"llm/retry",
-	"llm/retry-started",
-	"model/selection",
-	"permission/preset",
-	"plan/mode",
-	"request/context",
-	"request/header",
-	"sandbox/mode",
-	"schedule/change",
-	"session-log-deepseek/delivery-accepted",
-	"session/end-seed",
-	"session/title",
-	"session/title-llm-request",
-	"step/end",
-	"step/start",
-	"subagent/descriptor",
-	"subagent/model-selection-policy",
-	"team/member",
-	"team/message/delivered",
-	"team/message/queued",
-	"team/task",
-	"todo/write",
-	"tool-workflow/agent-end",
-	"tool-workflow/agent-start",
-	"tool-workflow/run-end",
-	"tool-workflow/run-start",
-	"tool/call",
-	"tool/code-dispatch",
-	"tool/code-dispatch-start",
-	"tool/result",
-	"turn/end",
-	"turn/start",
-	"user/message",
-	"web/deepseek-search-llm-request"
-]);
-//#endregion
 //#region lib/types/seq-ranges.js
 /** Lossless range encoding for JSONL `sourceEventSeqs` arrays. */
 function isStrictlyIncreasing(values) {
@@ -721,7 +776,7 @@ function validateSessionHeader(id, input) {
 	if (input === null || typeof input !== "object" || Array.isArray(input)) throw new Error("session header is not a plain JSON record");
 	const record = input;
 	if (Object.hasOwn(record, "seedLength")) throw new Error("session header has invalid field \"seedLength\"");
-	if (record.version !== 2) throw new Error(`session header version must be 2, got ${String(record.version)}`);
+	if (record.version !== 3) throw new Error(`session header version must be 3, got ${String(record.version)}`);
 	if (record.id !== id) throw new Error(`session header id "${String(record.id)}" does not match session id "${id}"`);
 	if (typeof record.createdAt !== "number" || !Number.isSafeInteger(record.createdAt) || record.createdAt < 0) throw new Error("session header createdAt must be a non-negative safe integer");
 	if (record.cwd !== void 0) {
@@ -746,7 +801,7 @@ function validateRestoredSessionHeader(id, input) {
 /** Detach, validate, and freeze the creation metadata published by a session. */
 function snapshotSessionHeader(id, source) {
 	const snapshot = snapshotJsonValue(source === void 0 ? {
-		version: 2,
+		version: 3,
 		id,
 		createdAt: Date.now(),
 		isSeeded: false
@@ -761,13 +816,17 @@ function snapshotSessionHeader(id, source) {
 * Use {@link snapshotSessionEvent} when exclusive ownership is not guaranteed.
 * @param event - exclusively owned event imported across a trusted boundary.
 * @returns the same event object with a validated, deeply frozen message.
+* @throws when event-local surface metadata, request-header fields, or message invariants are invalid; history relations are not checked.
 */
 function adoptSessionEvent(event) {
+	validateSessionEventData(event, `session event at seq ${event.seq}`);
+	validateSurfaceMetadata(event);
 	assertMessageEventShape(event, `session event at seq ${event.seq}`);
 	switch (event.type) {
 		case "user/message":
 			deepFreeze(event.data);
 			break;
+		case "system/message":
 		case "assistant/message":
 		case "tool/result":
 			deepFreeze(event.data.message);
@@ -786,6 +845,7 @@ function snapshotSessionEvent(event) {
 }
 /** Validate the fixed event envelope after one-pass JSON materialization. */
 function assertSessionEventEnvelope(value, index) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`seed event at index ${index} has an invalid event envelope`);
 	const event = value;
 	for (const key in event) switch (key) {
 		case "type":
@@ -801,8 +861,10 @@ function assertSessionEventEnvelope(value, index) {
 	const seq = event["seq"];
 	const time = event["time"];
 	if (typeof type !== "string" || typeof seq !== "number" || !Number.isSafeInteger(seq) || seq < 0 || Object.is(seq, -0) || typeof time !== "number" || !Number.isSafeInteger(time) || event["data"] === void 0 || event["ignorable"] !== void 0 && event["ignorable"] !== true) throw new Error(`seed event at index ${index} has an invalid event envelope`);
+	validateSessionEventData(event, `seed ${type} at index ${index}`);
 	switch (type) {
 		case "request/header":
+		case "system/message":
 		case "user/message":
 		case "assistant/attempt":
 		case "assistant/message":
@@ -816,14 +878,13 @@ function assertCurrentLlmShape(event, index) {
 	const data = event["data"];
 	const record = typeof data === "object" && data !== null ? data : void 0;
 	if (event["type"] === "request/header") {
-		const header = record?.["header"];
-		const headerRecord = typeof header === "object" && header !== null && !Array.isArray(header) ? header : void 0;
-		const config = headerRecord?.["config"];
+		const headerRecord = record?.["header"];
+		const config = headerRecord["config"];
 		if (!hasProviderModel(config)) throw new Error(`seed request/header at index ${index} lacks provider/model`);
 		const configRecord = config;
 		const reasoningEffort = configRecord["reasoningEffort"];
 		if (reasoningEffort !== void 0 && (typeof reasoningEffort !== "string" || reasoningEffort.length === 0)) throw new Error(`seed request/header at index ${index} has an invalid reasoningEffort`);
-		assertAdapterDefaults(headerRecord?.["adapterDefaults"], configRecord, index);
+		assertAdapterDefaults(headerRecord["adapterDefaults"], configRecord, index);
 		const reason = record?.["reason"];
 		if (reason !== "initial" && reason !== "resume" && reason !== "change" && reason !== "series") throw new Error(`seed request/header at index ${index} has an invalid reason`);
 		if (record?.["startsSeries"] !== void 0 && record["startsSeries"] !== true) throw new Error(`seed request/header at index ${index} has an invalid startsSeries marker`);
@@ -833,7 +894,7 @@ function assertCurrentLlmShape(event, index) {
 		assertAssistantSettlementShape(record, type, index);
 		return;
 	}
-	if (type !== "user/message" && type !== "assistant/message" && type !== "tool/result") return;
+	if (!isMessageEventType(type)) return;
 	assertMessageEventShape(event, `seed ${type} at index ${index}`);
 	if (type === "assistant/message") assertAssistantSettlementShape(record, type, index);
 }
@@ -851,21 +912,35 @@ function assertAdapterDefaults(value, config, index) {
 	const defaults = value;
 	if (Object.keys(defaults).some((key) => !allowedAdapterKeys.has(key)) || Object.values(defaults).some((marker) => marker !== true) || defaults["reasoningEffort"] === true && config["reasoningEffort"] === void 0 || defaults["maxTokens"] === true && config["maxTokens"] === void 0) throw new Error(`seed request/header at index ${index} has invalid adapterDefaults`);
 }
+/** The four surface event types whose payload carries an identified message. */
+function isMessageEventType(type) {
+	return type === "system/message" || type === "user/message" || type === "assistant/message" || type === "tool/result";
+}
+const MESSAGE_ROLE_BY_TYPE = {
+	"system/message": "system",
+	"user/message": "user",
+	"assistant/message": "assistant",
+	"tool/result": "user"
+};
 /** Validate only the event-specific invariants needed to safely replay a message. */
 function assertMessageEventShape(event, subject) {
 	const type = event["type"];
-	if (type !== "user/message" && type !== "assistant/message" && type !== "tool/result") return;
+	if (!isMessageEventType(type)) return;
 	const data = event["data"];
 	const record = typeof data === "object" && data !== null ? data : void 0;
 	const message = type === "user/message" ? record : record?.["message"];
 	if (typeof message !== "object" || message === null || typeof message["id"] !== "string" || message["id"] === "") throw new Error(`${subject} lacks an identified message`);
 	const messageRecord = message;
-	const expectedRole = type === "assistant/message" ? "assistant" : "user";
+	const expectedRole = MESSAGE_ROLE_BY_TYPE[type];
 	if (messageRecord["role"] !== expectedRole) throw new Error(`${subject} message must have role "${expectedRole}"`);
 	const source = messageRecord["source"];
 	if (typeof source !== "object" || source === null || typeof source["kind"] !== "string" || source["kind"] === "") throw new Error(`${subject} message has invalid source`);
 	if (!Array.isArray(messageRecord["content"])) throw new Error(`${subject} message has invalid content`);
 	const sourceRecord = source;
+	if (type === "system/message") {
+		if (sourceRecord["kind"] !== "plugin" || typeof sourceRecord["plugin"] !== "string" || sourceRecord["plugin"] === "") throw new Error(`${subject} message must have plugin source`);
+		return;
+	}
 	if (type === "assistant/message") {
 		if (sourceRecord["kind"] !== "model" || !hasProviderModel(sourceRecord)) throw new Error(`${subject} message must have model source`);
 		return;
@@ -1079,6 +1154,7 @@ var Session = class Session {
 	*   (BigInt, function, symbol, undefined, negative zero, non-finite number,
 	*   circular reference, sparse array, or an exotic object such as
 	*   Map/Set/Date/class instance), or when the candidate violates the
+	*   request-header empty-field or tool-error consistency rules, or the
 	*   canonical surface contract (marker shape and eligibility, unique
 	*   earlier source-event references, positional replacement validity, and complete
 	*   shadowed-node coverage). One iterative pass reads, validates, and
@@ -1108,6 +1184,7 @@ var Session = class Session {
 			data: dataSnapshot,
 			...surfaceMetadataSnapshot
 		});
+		validateSessionEventData(event, `session event "${type}" at seq ${event.seq}`);
 		this.surfaceManager.validateNext(event);
 		if (entry !== void 0) entry.appending = true;
 		try {
@@ -1312,7 +1389,7 @@ var SessionStore = class extends Service {
 		const seed = options?.seed;
 		const meta = options?.meta;
 		const header = {
-			version: 2,
+			version: 3,
 			id: sessionId,
 			createdAt: meta?.createdAt ?? Date.now(),
 			...meta?.cwd === void 0 ? {} : { cwd: meta.cwd },

package/lib/invariant.js

@@ -78,6 +78,9 @@ function validateEvent(trace, event, fail) {
 			};
 			break;
 		}
+		case "system/message":
+			requireOpenStep(trace, "system/message", event.data.turn, event.data.step, fail);
+			break;
 		case "user/message": break;
 		case "session/end-seed": break;
 		case "request/header":

package/lib/types/index.d.ts

@@ -15,7 +15,7 @@ import type { SessionSurface } from './surface.ts';
 export * from './types.ts';
 export { SessionPreparation } from './preparation.ts';
 export type { SessionPreparationOptions } from './preparation.ts';
-export type { AssistantMessage, ToolResultMessage, UserMessage } from '@deepseek-ai/dsh-llm';
+export type { AssistantMessage, SystemMessage, ToolResultMessage, UserMessage } from '@deepseek-ai/dsh-llm';
 export { interruptedTurnClosers, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN } from './repair.ts';
 export type { SessionSurface, SurfaceFoldReplacement, SurfaceFoldResult } from './surface.ts';
 export { deriveEventMessage, foldSurface, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEvent, isSurfaceEligibleType } from './surface.ts';
@@ -83,6 +83,7 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
  * Use {@link snapshotSessionEvent} when exclusive ownership is not guaranteed.
  * @param event - exclusively owned event imported across a trusted boundary.
  * @returns the same event object with a validated, deeply frozen message.
+ * @throws when event-local surface metadata, request-header fields, or message invariants are invalid; history relations are not checked.
  */
 export declare function adoptSessionEvent<T extends SessionEvent>(event: T): T;
 /**
@@ -223,6 +224,7 @@ export declare class Session {
      *   (BigInt, function, symbol, undefined, negative zero, non-finite number,
      *   circular reference, sparse array, or an exotic object such as
      *   Map/Set/Date/class instance), or when the candidate violates the
+     *   request-header empty-field or tool-error consistency rules, or the
      *   canonical surface contract (marker shape and eligibility, unique
      *   earlier source-event references, positional replacement validity, and complete
      *   shadowed-node coverage). One iterative pass reads, validates, and