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

package/lib/index.js

@@ -53,7 +53,7 @@ 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 = 3;
+const SESSION_FORMAT_VERSION = 4;
 //#endregion
 //#region lib/types/known-event-types.js
 /**
@@ -91,6 +91,7 @@ const KNOWN_SESSION_EVENT_TYPES = new Set([
 	"compaction/start",
 	"compaction/summary",
 	"deliverables/presented",
+	"developer/message",
 	"feedback/message-delete",
 	"feedback/message-put",
 	"feedback/record",
@@ -152,6 +153,7 @@ const MESSAGE_PROJECTION_EVENT_TYPES = new Set(["image/offload"]);
 /** Runtime counterpart of the message-producing event union. */
 const SURFACE_EVENT_TYPES = new Set([
 	"system/message",
+	"developer/message",
 	"user/message",
 	"assistant/message",
 	"tool/result"
@@ -159,7 +161,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 four message-producing event types.
+* @returns true for one of the message-producing event types.
 */
 function isSurfaceEligibleType(type) {
 	return SURFACE_EVENT_TYPES.has(type);
@@ -200,7 +202,7 @@ function isReplacementSurfaceEvent(event) {
 /**
 * Project a single event into the LLM message it derives to, or null when it
 * produces none — a non-surface event (attempt, boundary, log-only record) or an
-* empty-content assistant/message (which exists only to host usage). A caller
+* empty-content system, developer, or assistant message. A caller
 * reconstructing model input supplies the same prefix's `projectedMessages`
 * from {@link foldSurface}; without that map this function reads original
 * event content. Session instance methods apply the live projection. Messages
@@ -215,6 +217,7 @@ function deriveEventMessage(event, projectedMessages) {
 	switch (event.type) {
 		case "user/message": return event.data;
 		case "system/message":
+		case "developer/message":
 		case "assistant/message":
 			if (event.data.message.content.length === 0) return null;
 			return event.data.message;
@@ -227,14 +230,33 @@ function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /**
-* Reject noncanonical request-header fields and contradictory tool failure metadata.
+* Reject noncanonical request-header fields, developer roles/content, 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.
+* @throws when request-header fields, developer roles/content, or tool failure metadata are invalid.
 */
 function validateSessionEventData(event, subject) {
 	const data = event.data;
+	if (SURFACE_EVENT_TYPES.has(event.type) && isRecord(data)) {
+		const message = event.type === "user/message" ? data : data["message"];
+		if (isRecord(message)) {
+			if (event.type === "developer/message" !== (message["role"] === "developer")) throw new Error(`${subject} developer/message and developer role must occur together`);
+			if (message["role"] !== "developer" && Array.isArray(message["content"]) && message["content"].some((block) => isRecord(block) && (block["type"] === "tool-addition" || block["type"] === "tool-removal"))) throw new Error(`${subject} tool-change blocks require developer role`);
+			if (event.type === "developer/message" && Array.isArray(message["content"])) {
+				let hasAdditions = false;
+				for (const block of message["content"]) {
+					if (!isRecord(block) || block["type"] !== "tool-addition" && block["type"] !== "tool-removal") continue;
+					if (typeof block["toolName"] !== "string" || block["toolName"].length === 0) throw new Error(`${subject} ${block["type"]} requires a nonempty toolName`);
+					if (block["type"] === "tool-addition") {
+						hasAdditions = true;
+						if (Object.hasOwn(block, "tool")) throw new Error(`${subject} tool-addition must omit inline tool definitions`);
+					}
+				}
+				if (hasAdditions ? !isEventSeq(data["headerSeq"]) : Object.hasOwn(data, "headerSeq")) throw new Error(`${subject} requires headerSeq exactly when tool additions are present`);
+			}
+		}
+	}
 	if (event.type === "request/header") {
 		if (!isRecord(data)) throw new Error(`${subject} data must be an object`);
 		const header = data["header"];
@@ -247,9 +269,7 @@ function validateSessionEventData(event, subject) {
 		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`);
+		if (!isRecord(message) || message["isError"] !== true) throw new Error(`${subject} error requires message.isError === true`);
 	}
 }
 /** Create an empty surface fold state. */
@@ -307,6 +327,23 @@ function assertSourceEventReferences(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(", ")}`);
 }
+/** Resolve tool additions against their immutable historical request header. */
+function assertDeveloperHeader(event, events, baseSeq) {
+	if (event.type !== "developer/message") return;
+	validateSessionEventData(event, `developer/message at seq ${event.seq}`);
+	if (event.data.headerSeq === void 0) return;
+	const headerSeq = event.data.headerSeq;
+	const headerEvent = events[headerSeq - baseSeq];
+	if (headerSeq >= event.seq || headerEvent?.type !== "request/header") throw new Error("developer/message headerSeq must reference an earlier request/header");
+	for (const block of event.data.message.content) {
+		if (block.type !== "tool-addition") continue;
+		const definitions = headerEvent.data.header.tools?.filter((tool) => tool.name === block.toolName) ?? [];
+		if (definitions.length !== 1) throw new Error(`developer/message tool-addition "${block.toolName}" must name exactly one tool in headerSeq ${headerSeq}`);
+		const definition = definitions[0];
+		if (typeof definition.description !== "string" || !isRecord(definition.parameters)) throw new Error(`developer/message tool-addition "${block.toolName}" requires a complete tool definition in headerSeq ${headerSeq}`);
+		if (Object.hasOwn(definition, "deferLoading") && definition.deferLoading !== true) throw new Error("developer/message referenced tool deferLoading must be true when present");
+	}
+}
 /**
 * 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.
@@ -359,21 +396,13 @@ function assertToolResultRewrite(event, shadowedSeqs, events, baseSeq) {
 		if (original?.type !== "tool/result") throw new Error("tool/result surface replacement must target a current tool/result");
 		const originalRest = { ...original.data };
 		const replacementRest = { ...event.data };
-		const originalResult = original.data.message.content[0];
-		const replacementResult = event.data.message.content[0];
 		originalRest["message"] = {
 			...original.data.message,
-			content: [{
-				...originalResult,
-				content: null
-			}]
+			content: null
 		};
 		replacementRest["message"] = {
 			...event.data.message,
-			content: [{
-				...replacementResult,
-				content: null
-			}]
+			content: null
 		};
 		if (!isDeepEqualJson(originalRest, replacementRest)) throw new Error("tool/result surface replacement may change only content");
 	}
@@ -393,6 +422,7 @@ function assertSystemHeadRewrite(event, state, startIdx, shadowedSeqs, events, b
 function planSurfaceEvent(state, event, expectedSeq, events, baseSeq, projections) {
 	if (event.seq !== expectedSeq) throw new Error(`session event seq ${event.seq} is not contiguous; expected ${expectedSeq}`);
 	const surfaceOp = validateSurfaceMetadata(event);
+	assertDeveloperHeader(event, events, baseSeq);
 	const projection = projections.find((item) => item.type === event.type);
 	if (projection !== void 0) return {
 		kind: "project",
@@ -607,64 +637,49 @@ function foldRequestHeader(events, from) {
 	return state;
 }
 //#endregion
-//#region lib/types/preparation.js
-/**
-* Ownership of one unpublished Session before registry publication.
-* @module @deepseek-ai/dsh-session/preparation
-*/
-/**
-* One exact unpublished Session and the provider state that keeps it usable.
-* Disposal is synchronous and idempotent. Providers decide whether release
-* returns the Session to a cache or discards it; publication may consume that
-* state before disposal, making the callback a no-op.
-*/
-var SessionPreparation = class SessionPreparation {
-	options;
-	released = false;
-	/** The exact Session to use for setup and publication. */
-	session;
-	constructor(session, options) {
-		this.options = options;
-		this.session = session;
-	}
-	/**
-	* Wrap an unpublished Session in one preparation lifetime.
-	* @param session - exact unpublished Session.
-	* @param options - optional provider release behavior.
-	* @returns a preparation disposed after publication or rollback.
-	*/
-	static create(session, options) {
-		return new SessionPreparation(session, options ?? {});
-	}
-	/** Release provider state once when this preparation leaves its caller. */
-	[Symbol.dispose]() {
-		if (this.released) return;
-		this.released = true;
-		this.options.release?.();
-	}
-};
-//#endregion
 //#region lib/types/repair.js
 /**
-* Crash-recovery repair for an interrupted session log. It preserves a fully
-* written final turn and supplies the missing tool, step, and turn boundaries
-* needed to resume with a provider-valid transcript.
+* 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.
 * @module @deepseek-ai/dsh-session/repair
 */
 /** Recovery code for an assistant tool request that never reached a recorded call start. */
 const TOOL_NOT_STARTED = "TOOL_NOT_STARTED";
 /** Recovery code for a recorded tool call whose completed outcome was not durably recorded. */
 const TOOL_OUTCOME_UNKNOWN = "TOOL_OUTCOME_UNKNOWN";
+/** Model-visible wording of the synthetic error tool results, keyed by cause. */
+const CLOSER_TEXT = {
+	interrupted: {
+		started: "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.",
+		notStarted: "The tool call was interrupted before the Harness recorded it as started. Retry it if it is still needed."
+	},
+	forked: {
+		started: "The history inherited by this branch records this tool call starting but does not include its result. The parent session may have completed it after the fork point. 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.",
+		notStarted: "The history inherited by this branch has no record of this tool call starting. The parent session may have executed it after the fork point. 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."
+	}
+};
 /**
 * Return deterministic synthetic events that close an open tail turn. Unmatched
-* calls receive error results first, followed by an open `step/end` and an
-* interrupted `turn/end`; sequences continue the log and timestamps reuse the
-* last real event. A balanced or empty log returns no events.
+* 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.
 *
-* @param events - the loaded durable log to scan (a valid committed prefix, possibly with a crash tail).
+* 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.
 * @returns the synthetic closer events to append after `events`, in order; empty when the log is already balanced.
 */
-function interruptedTurnClosers(events) {
+function openTurnClosers(events, cause) {
 	let openTurn = null;
 	let openStep = null;
 	const pendingCalls = /* @__PURE__ */ new Map();
@@ -705,23 +720,21 @@ function interruptedTurnClosers(events) {
 	let seq = last.seq + 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(`interrupted-tool-result-${callId}-${seq}`),
-			role: "user",
+			id: brandString(`${cause.kind}-tool-result-${callId}-${seq}`),
+			role: "tool",
+			toolCallId: callId,
+			isError: true,
 			source: {
 				kind: "tool",
 				callId
 			},
 			content: [{
-				type: "tool-result",
-				toolCallId: callId,
-				isError: true,
-				content: [{
-					type: "text",
-					text: started ? "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." : "The tool call was interrupted before the Harness recorded it as started. Retry it if it is still needed."
-				}]
+				type: "text",
+				text: started ? text.started : text.notStarted
 			}]
 		});
 		closers.push({
@@ -759,11 +772,87 @@ function interruptedTurnClosers(events) {
 		time,
 		data: {
 			turn: openTurn,
-			reason: { kind: "interrupted" }
+			reason: { kind: cause.kind }
 		}
 	});
 	return closers;
 }
+/**
+* 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.
+*
+* @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.
+*/
+function interruptedTurnClosers(events) {
+	return openTurnClosers(events, { kind: "interrupted" });
+}
+//#endregion
+//#region lib/types/fork.js
+/**
+* Fork seed construction over an exact source-event prefix.
+* @module @deepseek-ai/dsh-session/fork
+*/
+/**
+* Copy an inclusive event prefix, mark its inherited cut, and close its open tail with forked results
+* and step/turn endings. Closed steps and turns are preserved unchanged.
+* The caller validates that the boundary is an existing contiguous event seq;
+* Session construction snapshots the borrowed events before publication.
+*
+* @param events - source log with contiguous seqs from zero.
+* @param boundary - inclusive source event seq the child inherits through.
+* @returns a new array retaining the source event objects, followed by synthetic
+*   closers outside the inherited prefix counted by `inheritedEventCount`.
+*/
+function buildForkSeed(events, boundary) {
+	const prefix = events.slice(0, boundary + 1);
+	prefix.push({
+		type: "session/end-seed",
+		seq: SessionSeq(boundary + 1),
+		time: events[boundary].time,
+		data: { inherited: true }
+	});
+	return prefix.concat(openTurnClosers(prefix, { kind: "forked" }));
+}
+//#endregion
+//#region lib/types/preparation.js
+/**
+* Ownership of one unpublished Session before registry publication.
+* @module @deepseek-ai/dsh-session/preparation
+*/
+/**
+* One exact unpublished Session and the provider state that keeps it usable.
+* Disposal is synchronous and idempotent. Providers decide whether release
+* returns the Session to a cache or discards it; publication may consume that
+* state before disposal, making the callback a no-op.
+*/
+var SessionPreparation = class SessionPreparation {
+	options;
+	released = false;
+	/** The exact Session to use for setup and publication. */
+	session;
+	constructor(session, options) {
+		this.options = options;
+		this.session = session;
+	}
+	/**
+	* Wrap an unpublished Session in one preparation lifetime.
+	* @param session - exact unpublished Session.
+	* @param options - optional provider release behavior.
+	* @returns a preparation disposed after publication or rollback.
+	*/
+	static create(session, options) {
+		return new SessionPreparation(session, options ?? {});
+	}
+	/** Release provider state once when this preparation leaves its caller. */
+	[Symbol.dispose]() {
+		if (this.released) return;
+		this.released = true;
+		this.options.release?.();
+	}
+};
 //#endregion
 //#region lib/types/seq-ranges.js
 /** Lossless range encoding for JSONL `sourceEventSeqs` arrays. */
@@ -834,7 +923,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 !== 3) throw new Error(`session header version must be 3, got ${String(record.version)}`);
+	if (record.version !== 4) throw new Error(`session header version must be 4, 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) {
@@ -859,7 +948,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: 3,
+		version: 4,
 		id,
 		createdAt: Date.now(),
 		isSeeded: false
@@ -884,6 +973,7 @@ function adoptSessionEvent(event) {
 		case "user/message":
 			deepFreeze(event.data);
 			break;
+		case "developer/message":
 		case "system/message":
 		case "assistant/message":
 		case "tool/result":
@@ -922,6 +1012,7 @@ function assertSessionEventEnvelope(value, index) {
 	validateSessionEventData(event, `seed ${type} at index ${index}`);
 	switch (type) {
 		case "request/header":
+		case "developer/message":
 		case "system/message":
 		case "user/message":
 		case "assistant/attempt":
@@ -970,15 +1061,16 @@ 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. */
+/** The 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";
+	return type === "developer/message" || type === "system/message" || type === "user/message" || type === "assistant/message" || type === "tool/result";
 }
 const MESSAGE_ROLE_BY_TYPE = {
 	"system/message": "system",
+	"developer/message": "developer",
 	"user/message": "user",
 	"assistant/message": "assistant",
-	"tool/result": "user"
+	"tool/result": "tool"
 };
 /** Validate only the event-specific invariants needed to safely replay a message. */
 function assertMessageEventShape(event, subject) {
@@ -996,7 +1088,7 @@ function assertMessageEventShape(event, subject) {
 	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`);
+		if (sourceRecord["kind"] !== "system-prompt") throw new Error(`${subject} message must have system-prompt source`);
 		return;
 	}
 	if (type === "assistant/message") {
@@ -1005,10 +1097,7 @@ function assertMessageEventShape(event, subject) {
 	}
 	if (type !== "tool/result") return;
 	if (sourceRecord["kind"] !== "tool" || typeof sourceRecord["callId"] !== "string" || sourceRecord["callId"] === "") throw new Error(`${subject} message must have tool source`);
-	const content = messageRecord["content"];
-	const block = content[0];
-	if (content.length !== 1 || typeof block !== "object" || block === null || block["type"] !== "tool-result" || !Array.isArray(block["content"])) throw new Error(`${subject} message must contain one tool-result block`);
-	if (block["toolCallId"] !== sourceRecord["callId"]) throw new Error(`${subject} message has mismatched tool call ids`);
+	if (messageRecord["toolCallId"] !== sourceRecord["callId"]) throw new Error(`${subject} message has mismatched tool call ids`);
 }
 /** Whether an unknown value carries the current provider/model pair. */
 function hasProviderModel(value) {
@@ -1065,30 +1154,26 @@ var Session = class Session {
 		return this.header.id;
 	}
 	/**
-	* The first seq appended IN THIS PROCESS: the length of the constructor
-	* seed (0 without one). Events with smaller seq values entered through
-	* construction — replay, fork, or resume — and were never published on the
-	* `session/event` firehose (constructor seeds do not emit). This offset marks
-	* the constructor-input boundary for lifecycle ownership and persistence
-	* adoption; consumers that need complete canonical history still start at
-	* seq 0. Distinct from {@link inheritedEventCount}, the DURABLE
-	* fork-lineage cut: a resumed session's constructor seed is its full stored
-	* log, while the inherited count keeps the original fork value — this field is the
-	* in-process construction fact.
+	* The constructor seed length (0 without one), before any marker appended
+	* during construction. Seed events never publish on `session/event`. A
+	* marker appended before the store attaches occupies this seq without
+	* publishing either; otherwise this seq is available for the next append.
 	*
-	* Not persisted itself: a seeded session projects it into the log as the
-	* `session/end-seed` event, which is what a consumer reading STORED history
-	* reads. Locate the LAST such event, not necessarily one at this seq — a
-	* seed already ending in one is not re-marked, so reopening an untouched
-	* session leaves that event at a smaller seq than `firstLiveSeq`. Prefer
-	* this field in-process: it is exact before the marker reaches storage.
-	*
-	* When this lifecycle appends the marker, it occupies this seq before the
-	* store attaches and therefore does not publish either. Otherwise this seq
-	* holds an ordinary published write.
+	* This in-process offset is not persisted. A fork seed can already contain
+	* the child's inherited marker and synthetic closers, so its child-owned
+	* history starts at {@link inheritedEventCount}, before this offset. A
+	* resumed Session's seed contains its full stored log, while its inherited
+	* count keeps the durable fork cut. Consumers needing complete canonical
+	* history start at seq 0.
 	*/
 	firstLiveSeq;
 	/**
+	* First event produced for this object lifecycle. A new fork includes its
+	* child-owned seed marker and closers; a restored Session starts after its
+	* complete stored prefix. This in-process capture offset is not persisted.
+	*/
+	firstLifecycleSeq;
+	/**
 	* Create a detached session by validating and snapshotting borrowed seed
 	* events and storage metadata.
 	* @param id - session identity.
@@ -1142,10 +1227,14 @@ var Session = class Session {
 		const inheritedEventCount = SessionLogOffset(suppliedInheritedEventCount ?? 0);
 		if (!this.header.isSeeded && inheritedEventCount !== 0) throw new Error("unseeded session inherited event count must be 0");
 		if (inheritedEventCount > this.log.length) throw new Error("session inherited event count exceeds its event log");
-		if (mode === "snapshot" && this.header.isSeeded && inheritedEventCount !== this.log.length) throw new Error("seeded session constructor seed must equal its inherited prefix");
+		const seedMarker = this.log[inheritedEventCount];
+		const markedSeed = seedMarker?.type === "session/end-seed" && seedMarker.data.inherited === true;
+		if (mode === "snapshot" && this.header.isSeeded && inheritedEventCount !== this.log.length && !markedSeed) throw new Error("seeded session constructor seed must equal its inherited prefix or mark its inherited cut");
+		if (markedSeed && this.log.slice(inheritedEventCount + 1).some((event) => event.type === "session/end-seed" && event.data.inherited === true)) throw new Error("session inherited event count must identify the final inherited marker");
 		this.inheritedEventCount = inheritedEventCount;
-		if (seed !== void 0 && mode === "snapshot" && this.header.isSeeded) this.append("session/end-seed", { inherited: true });
-		else if (seed !== void 0 && this.log.at(-1)?.type !== "session/end-seed") this.append("session/end-seed", {});
+		this.firstLifecycleSeq = mode === "snapshot" && this.header.isSeeded ? inheritedEventCount : this.firstLiveSeq;
+		if (seed !== void 0 && mode === "snapshot" && this.header.isSeeded && !markedSeed) this.append("session/end-seed", { inherited: true });
+		else if (seed !== void 0 && !(mode === "snapshot" && this.header.isSeeded) && this.log.at(-1)?.type !== "session/end-seed") this.append("session/end-seed", {});
 	}
 	/** Cached immutable full snapshot of the private append-only log. */
 	eventsSnapshot;
@@ -1479,7 +1568,7 @@ var SessionStore = class extends Service {
 		const seed = options?.seed;
 		const meta = options?.meta;
 		const header = {
-			version: 3,
+			version: 4,
 			id: sessionId,
 			createdAt: meta?.createdAt ?? Date.now(),
 			...meta?.cwd === void 0 ? {} : { cwd: meta.cwd },
@@ -1651,10 +1740,12 @@ var SessionStore = class extends Service {
 		return [...this.store.values()].map((entry) => entry.session);
 	}
 	/**
-	* Create a live child session from a stable prefix of a live source.
+	* Create a live child session from an exact prefix of a live source.
 	* `boundary` is an inclusive source event seq; omitted means the source's
-	* current last event. The selected slice may end with a between-turn event
-	* but must not end inside an open turn.
+	* current last event. An open tail receives synthetic tool results and
+	* step/turn closers with the forked cause. Closed steps and turns remain
+	* unchanged, including any failed tool calls already missing results.
+	* `inheritedEventCount` counts only copied source events, excluding these closers.
 	*
 	* @param source - Live source session object or id.
 	* @param boundary - Inclusive source event seq to fork through; omitted means
@@ -1667,10 +1758,12 @@ var SessionStore = class extends Service {
 	fork(source, boundary, childSessionId) {
 		if (childSessionId !== void 0 && this.get(childSessionId) !== void 0) throw new SessionForkError(`session "${childSessionId}" already exists`, "SESSION_ALREADY_EXISTS");
 		const liveSource = this._resolveForkSource(source);
-		const seed = this._forkSeed(liveSource, boundary);
+		const events = liveSource.snapshotEvents();
+		const resolved = this._forkBoundary(liveSource.id, events, boundary);
+		const seed = resolved === void 0 ? [] : buildForkSeed(events, resolved);
 		return this.create(childSessionId, {
 			seed,
-			inheritedEventCount: SessionLogOffset(seed.length),
+			inheritedEventCount: SessionLogOffset(resolved === void 0 ? 0 : resolved + 1),
 			meta: {
 				...liveSource.header.cwd !== void 0 ? { cwd: liveSource.header.cwd } : {},
 				parentSession: liveSource.id,
@@ -1678,25 +1771,22 @@ var SessionStore = class extends Service {
 			}
 		});
 	}
-	_forkSeed(session, requestedBoundary) {
-		const lastEvent = session.snapshotEvents().at(-1);
+	_forkBoundary(sessionId, events, requestedBoundary) {
+		const lastEvent = events.at(-1);
 		let boundary;
 		if (requestedBoundary !== void 0) boundary = requestedBoundary;
 		else {
-			if (lastEvent === void 0) return [];
+			if (lastEvent === void 0) return void 0;
 			boundary = lastEvent.seq;
 		}
-		if (!Number.isSafeInteger(boundary) || boundary < 0) throw new SessionForkError(`fork boundary for session "${session.id}" must be a non-negative safe integer, got ${String(boundary)}`, "INVALID_BOUNDARY");
-		if (boundary >= session.seq) {
+		if (!Number.isSafeInteger(boundary) || boundary < 0) throw new SessionForkError(`fork boundary for session "${sessionId}" must be a non-negative safe integer, got ${String(boundary)}`, "INVALID_BOUNDARY");
+		if (boundary >= events.length) {
 			const lastSeq = lastEvent?.seq;
-			throw new SessionForkError(`fork boundary ${boundary} does not exist in session "${session.id}" (last seq: ${lastSeq ?? "none"})`, "INVALID_BOUNDARY");
+			throw new SessionForkError(`fork boundary ${boundary} does not exist in session "${sessionId}" (last seq: ${lastSeq ?? "none"})`, "INVALID_BOUNDARY");
 		}
-		const boundaryEvent = session.eventAt(boundary);
-		if (boundaryEvent === void 0 || boundaryEvent.seq !== boundary) throw new SessionForkError(`fork boundary ${boundary} does not match a contiguous event seq in session "${session.id}"`, "INVALID_BOUNDARY");
-		const events = session.snapshotEvents(SessionLogOffset(0), SessionLogOffset(boundary + 1));
-		const lastTurnBoundary = events.findLast((event) => event.type === "turn/start" || event.type === "turn/end");
-		if (lastTurnBoundary?.type === "turn/start") throw new SessionForkError(`fork boundary ${boundary} in session "${session.id}" ends inside open turn ${lastTurnBoundary.data.turn}`, "OPEN_TURN");
-		return events;
+		const boundaryEvent = events[boundary];
+		if (boundaryEvent === void 0 || boundaryEvent.seq !== boundary) throw new SessionForkError(`fork boundary ${boundary} does not match a contiguous event seq in session "${sessionId}"`, "INVALID_BOUNDARY");
+		return boundary;
 	}
 	_resolveForkSource(source) {
 		if (typeof source === "string") {
@@ -1711,4 +1801,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, 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, adoptSessionEvent, buildForkSeed, canonicalHeader, decodeSeqRanges, deriveEventMessage, encodeSeqRanges, foldRequestHeader, foldSurface, headerEquals, interruptedTurnClosers, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEligibleType, isSurfaceEvent, snapshotSessionEvent };

package/lib/invariant.js

@@ -44,6 +44,9 @@ function validateEvent(trace, event, fail) {
 			if (event.data.step !== trace.nextStep) fail(`step/start expected step ${trace.nextStep} in turn ${event.data.turn}, got ${event.data.step}`);
 			openStep = event.data.step;
 			break;
+		case "developer/message":
+			requireOpenStep(trace, "developer/message", event.data.turn, event.data.step, fail);
+			break;
 		case "step/end":
 			requireOpenStep(trace, "step/end", event.data.turn, event.data.step, fail);
 			pendingCalls = { kind: "clear" };
@@ -70,7 +73,7 @@ function validateEvent(trace, event, fail) {
 			}
 			requireOpenStep(trace, "tool/result", event.data.turn, event.data.step, fail);
 			const callId = event.data.message.source.callId;
-			const syntheticNotStarted = event.data.message.content[0].isError === true && event.data.error?.code === "TOOL_NOT_STARTED";
+			const syntheticNotStarted = event.data.message.isError === true && event.data.error?.code === "TOOL_NOT_STARTED";
 			if (!trace.pendingCalls.has(callId) && !syntheticNotStarted) fail(`tool/result for ${callId} with no prior tool/call in this step`);
 			pendingCalls = {
 				kind: "delete",

package/lib/types/fork.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Fork seed construction over an exact source-event prefix.
+ * @module @deepseek-ai/dsh-session/fork
+ */
+import type { SessionEvent, SessionSeq as SessionSeqType } from './types.ts';
+/**
+ * Copy an inclusive event prefix, mark its inherited cut, and close its open tail with forked results
+ * and step/turn endings. Closed steps and turns are preserved unchanged.
+ * The caller validates that the boundary is an existing contiguous event seq;
+ * Session construction snapshots the borrowed events before publication.
+ *
+ * @param events - source log with contiguous seqs from zero.
+ * @param boundary - inclusive source event seq the child inherits through.
+ * @returns a new array retaining the source event objects, followed by synthetic
+ *   closers outside the inherited prefix counted by `inheritedEventCount`.
+ */
+export declare function buildForkSeed(events: readonly SessionEvent[], boundary: SessionSeqType): SessionEvent[];
+//# sourceMappingURL=fork.d.ts.map