@deepseek-ai/dsh-api-session-controller 0.1.2-alpha.3 → 0.1.2-alpha.5

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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:
 #   pnpm run verify-translation-pairing --write packages/api/session-controller/README.md
-README.md: 94e8697cd7f5bf75746edd5d691956e680d9b261
-README.zh.md: 0228ca15624413fcd5cb6e17afb8aaf0a28f780a
+README.md: b3d22a340fff6a49270de520a043a1c8dfdbf096
+README.zh.md: 45590a53db17b32cc59f6107957c284b53ee8302

package/README.md

@@ -72,3 +72,5 @@ No direct effect; model requests remain owned by the Agent and LLM packages.
 None.
 
 </details>
+
+**Runtime invariant:** No companion is published. Every page and frame is checked against the addressed durable Session.

package/README.zh.md

@@ -72,3 +72,5 @@ Session 对象还承载本地提交回显：`session.beginSubmission` 在调用
 无。
 
 </details>
+
+**运行时不变式：** 不发布伴生入口。每个分页与帧都会对照其指向的持久 Session 校验。

package/lib/client.js

@@ -176,6 +176,36 @@ window.__ModuleLoader__.load({
 			}
 		};
 		//#endregion
+		//#region ../../util/brand/lib/index.js
+		/**
+		* Apply a compile-time number brand without changing the value.
+		* @param value - number admitted by the domain that owns the target brand.
+		* @returns the same number with the requested compile-time brand.
+		*/
+		function brandNumber(value) {
+			return value;
+		}
+		//#endregion
+		//#region ../../core/session/lib/types/types.js
+		/**
+		* Admit a numeric value as an existing Session event position.
+		* @param value - non-negative safe integer admitted by the owning log operation.
+		* @returns the same number with the Session-sequence brand.
+		*/
+		function SessionSeq(value) {
+			if (!Number.isSafeInteger(value) || value < 0 || Object.is(value, -0)) throw new TypeError(`SessionSeq must be a non-negative safe integer, got ${String(value)}`);
+			return brandNumber(value);
+		}
+		/**
+		* Admit a numeric value as a Session log offset.
+		* @param value - non-negative safe integer used as a gap or prefix length.
+		* @returns the same number with the Session-log-offset brand.
+		*/
+		function SessionLogOffset(value) {
+			if (!Number.isSafeInteger(value) || value < 0 || Object.is(value, -0)) throw new TypeError(`SessionLogOffset must be a non-negative safe integer, got ${String(value)}`);
+			return brandNumber(value);
+		}
+		//#endregion
 		//#region ../../util/workspace-path/lib/index.js
 		/**
 		* Read the final non-empty segment of a Workspace path for display.
@@ -721,6 +751,14 @@ window.__ModuleLoader__.load({
 				return true;
 			}
 		};
+		//#endregion
+		//#region lib/types/client/sessions/session.js
+		function projectionsBaseline(value) {
+			return {
+				...value,
+				asOfSeq: value.asOfSeq === -1 ? -1 : SessionSeq(value.asOfSeq)
+			};
+		}
 		/**
 		* Owns a session's event window, lifecycle state, and observable
 		* snapshot. React bindings remain outside this data layer. Features see only
@@ -731,7 +769,7 @@ window.__ModuleLoader__.load({
 			sessionId;
 			remote;
 			options;
-			baseSeq = 0;
+			baseSeq = SessionLogOffset(0);
 			hasMore = false;
 			openState = "cold";
 			openError = null;
@@ -972,8 +1010,16 @@ window.__ModuleLoader__.load({
 					sessionId: this.sessionId,
 					title
 				});
-				if (result.ok) this.projections.apply("title", result.value.title, result.value.seq);
-				return result;
+				if (!result.ok) return result;
+				const seq = SessionSeq(result.value.seq);
+				this.projections.apply("title", result.value.title, seq);
+				return {
+					ok: true,
+					value: {
+						title: result.value.title,
+						seq
+					}
+				};
 			}
 			/**
 			* Execute one slash-command line against this session's agent — pure
@@ -1023,7 +1069,7 @@ window.__ModuleLoader__.load({
 			loadThrough(seq) {
 				if (this.openState !== "open" || !this.hasMore || this.baseSeq <= seq) return Promise.resolve();
 				if (this.jumpPromise !== null) {
-					this.jumpTargetSeq = Math.min(this.jumpTargetSeq ?? seq, seq);
+					this.jumpTargetSeq = SessionSeq(Math.min(this.jumpTargetSeq ?? seq, seq));
 					return this.jumpPromise;
 				}
 				if (this.loadingOlder) return Promise.resolve();
@@ -1067,7 +1113,7 @@ window.__ModuleLoader__.load({
 				this.openPromise = null;
 				this.openState = "cold";
 				this.openError = null;
-				this.baseSeq = 0;
+				this.baseSeq = SessionLogOffset(0);
 				this.notifier.markDirty();
 				await this.open();
 			}
@@ -1211,7 +1257,7 @@ window.__ModuleLoader__.load({
 			acceptEventChange(change) {
 				switch (change.type) {
 					case "replace":
-						this.installWindow(change.entries, change.hasMore, change.page.projections);
+						this.installWindow(change.entries, change.hasMore, change.page.projections === void 0 ? void 0 : projectionsBaseline(change.page.projections));
 						return;
 					case "prepend":
 						this.prependWindow(change.entries, change.hasMore);
@@ -1221,7 +1267,7 @@ window.__ModuleLoader__.load({
 			}
 			/** Replace the complete contiguous window and apply page-owned projection metadata. */
 			installWindow(entries, hasMore, projections) {
-				this.baseSeq = entries[0]?.event.seq ?? 0;
+				this.baseSeq = SessionLogOffset(entries[0]?.event.seq ?? 0);
 				this.hasMore = hasMore;
 				if (entries.some((entry) => entry.event.type === "turn/start")) this.firstPromptPendingTurn = false;
 				if (projections !== void 0) this.projections.seed(projections);
@@ -1231,7 +1277,7 @@ window.__ModuleLoader__.load({
 			}
 			/** Prepend one stream-validated history page. */
 			prependWindow(entries, hasMore) {
-				this.baseSeq = entries[0]?.event.seq ?? this.baseSeq;
+				this.baseSeq = entries[0] === void 0 ? this.baseSeq : SessionLogOffset(entries[0].event.seq);
 				this.hasMore = hasMore;
 				this.eventSource.prepend(entries, hasMore);
 			}
@@ -1356,6 +1402,9 @@ window.__ModuleLoader__.load({
 		}
 		//#endregion
 		//#region lib/types/client/sessions/manager.js
+		function sessionSeqCursor(value) {
+			return value === -1 ? -1 : SessionSeq(value);
+		}
 		function catalogAvailability(parentAvailable) {
 			return parentAvailable === void 0 ? {} : { parentAvailable };
 		}
@@ -1689,7 +1738,7 @@ window.__ModuleLoader__.load({
 								if (block === void 0) continue;
 								const store = this.projectionStore(s.sessionId);
 								const values = block.values;
-								for (const key of Object.keys(values)) store.apply(key, values[key], block.asOfSeq);
+								for (const key of Object.keys(values)) store.apply(key, values[key], sessionSeqCursor(block.asOfSeq));
 							}
 						} else {
 							this.listState = "error";
@@ -1840,7 +1889,7 @@ window.__ModuleLoader__.load({
 					return;
 				}
 				if (frame.type === "projection") {
-					this.projectionStore(frame.sessionId).apply(frame.key, frame.value, frame.seq);
+					this.projectionStore(frame.sessionId).apply(frame.key, frame.value, SessionSeq(frame.seq));
 					this.notifier.markDirty();
 					return;
 				}
@@ -1860,8 +1909,12 @@ window.__ModuleLoader__.load({
 				for (const [sessionId, jobs] of Object.entries(baseline.jobs)) if (jobs.length > 0) this.jobsBySession.set(sessionId, jobs);
 				for (const [sessionId, block] of Object.entries(baseline.projections)) {
 					const store = this.projectionStore(sessionId);
-					store.truncate(block.asOfSeq);
-					store.seed(block);
+					const asOfSeq = sessionSeqCursor(block.asOfSeq);
+					store.truncate(asOfSeq);
+					store.seed({
+						...block,
+						asOfSeq
+					});
 				}
 				for (const [sessionId, session] of this.sessions) session.replaceControl(this.queues.get(sessionId) ?? []);
 				this.notifier.markDirty();
@@ -1876,7 +1929,7 @@ window.__ModuleLoader__.load({
 				const projections = summary.projections;
 				if (projections !== void 0) {
 					const store = this.projectionStore(summary.sessionId);
-					for (const [key, value] of Object.entries(projections.values)) store.apply(key, value, projections.asOfSeq);
+					for (const [key, value] of Object.entries(projections.values)) store.apply(key, value, sessionSeqCursor(projections.asOfSeq));
 				}
 				if (summary.origin === "subagent" && summary.parentSessionId !== void 0) this.markCatalogParentExpandable(summary.parentSessionId);
 				if (summary.parentSessionId !== void 0 && (this.selected === summary.parentSessionId || this.openCatalogs.has(summary.parentSessionId))) this.scheduleCatalogRefresh(summary.parentSessionId);
@@ -2400,7 +2453,7 @@ window.__ModuleLoader__.load({
 				const sourceTitle = opts.increaseTitle ? this.list.getSnapshot().byId[opts.sessionId]?.title : void 0;
 				const result = await this.manager.fork({
 					sessionId: opts.sessionId,
-					...opts.atSeq === void 0 ? {} : { atSeq: Math.floor(opts.atSeq) }
+					...opts.atSeq === void 0 ? {} : { atSeq: SessionSeq(Math.floor(opts.atSeq)) }
 				});
 				if (!result.ok) throw new SessionForkError(result.error, opts.sessionId);
 				this.projectList();

package/lib/index.js

@@ -8,10 +8,10 @@ import { SessionQueryError } from "@deepseek-ai/dsh-session-query";
 import { randomUUID } from "node:crypto";
 import { brandString } from "@deepseek-ai/dsh-brand";
 import { AttachmentError, admitPromptContent } from "@deepseek-ai/dsh-attachment";
+import { SessionLogOffset, SessionSeq, isAppendSurfaceEvent } from "@deepseek-ai/dsh-session";
 import { SessionTitleInvalidError } from "@deepseek-ai/dsh-session-title";
 import { canonicalClientTimeZone } from "@deepseek-ai/dsh-util-time";
 import { Deque } from "@deepseek-ai/dsh-deque";
-import { isAppendSurfaceEvent } from "@deepseek-ai/dsh-session";
 import { isChunkRow, packChunkRuns } from "@deepseek-ai/dsh-session/chunk-rows";
 import { z as z$1 } from "zod";
 import { isUserInvocable } from "@deepseek-ai/dsh-skill";
@@ -154,6 +154,7 @@ async function inspectApiSession(ctx, sessionId, signal) {
 			if (observation.header.cwd === void 0) throw new ApiSessionNotFound(`session "${sessionId}" not found`);
 			return {
 				meta: observation.header,
+				inheritedEventCount: observation.inheritedEventCount,
 				events: [...observation.events]
 			};
 		} catch (e_1) {
@@ -658,7 +659,12 @@ var SessionCommandController = class {
 			hasError: false
 		};
 		try {
-			if (request.atSeq !== void 0 && (!Number.isInteger(request.atSeq) || request.atSeq < 0)) throw new RemoteError("gateway/bad-request", "atSeq must be a non-negative integer", {});
+			let atSeq;
+			try {
+				atSeq = request.atSeq === void 0 ? void 0 : SessionSeq(request.atSeq);
+			} catch {
+				throw new RemoteError("gateway/bad-request", "atSeq must be a non-negative safe integer", {});
+			}
 			let observed;
 			try {
 				observed = await this.ctx.sessionQuery.observeSession(request.sessionId);
@@ -668,11 +674,10 @@ var SessionCommandController = class {
 			}
 			const source = __addDisposableResource$4(env_1, observed, false);
 			const lastSeq = source.events.at(-1)?.seq ?? -1;
-			const atSeq = request.atSeq;
 			const boundary = (atSeq === void 0 ? void 0 : source.events.find((event) => event.type === "turn/end" && event.seq >= atSeq)) ?? (atSeq === void 0 || atSeq > lastSeq ? source.events.findLast((event) => event.type === "turn/end") : void 0);
 			if (boundary === void 0) throw new RemoteError("session/fork-unavailable", atSeq !== void 0 && atSeq <= lastSeq ? `session "${request.sessionId}" has not completed the turn containing event ${String(atSeq)}` : `session "${request.sessionId}" has no completed turn to fork from`, { sessionId: request.sessionId });
-			let cut = boundary.seq + 1;
-			while (cut < source.events.length && source.events[cut]?.type !== "turn/start") cut++;
+			let cut = SessionLogOffset(boundary.seq + 1);
+			while (cut < source.events.length && source.events[cut]?.type !== "turn/start") cut = SessionLogOffset(cut + 1);
 			let workspace;
 			try {
 				workspace = await this.forkWorkspace(source.header);
@@ -686,10 +691,11 @@ var SessionCommandController = class {
 				await this.ctx.agents.create({
 					sessionId: childId,
 					seed: source.events.slice(0, cut),
+					inheritedEventCount: cut,
 					meta: {
 						...source.header.cwd === void 0 ? {} : { cwd: source.header.cwd },
 						parentSession: source.header.id,
-						seedLength: cut,
+						isSeeded: true,
 						...composition.agentPreset === void 0 ? {} : { agentPreset: composition.agentPreset }
 					},
 					agentOptions: {
@@ -854,7 +860,7 @@ var SessionCommandController = class {
 		if (attached !== void 0) return {
 			id: attached.id,
 			header: attached.header,
-			events: [...attached.events]
+			events: attached.snapshotEvents()
 		};
 		const inspected = await inspectApiSession(this.ctx, sessionId);
 		return {
@@ -1203,14 +1209,16 @@ var SessionHistoryController = class {
 		};
 		try {
 			validatePageRequest(request);
+			const throughSeq = request.throughSeq === -1 ? -1 : SessionSeq(request.throughSeq);
+			const beforeSeq = request.beforeSeq === void 0 ? void 0 : SessionLogOffset(request.beforeSeq);
 			const source = __addDisposableResource$3(env_1, await this.sourceFor(request.address, signal, false), false);
 			signal.throwIfAborted();
 			const sourceLog = source.events;
 			const sourceCursor = sourceLog.at(-1)?.seq ?? -1;
-			if (request.throughSeq > sourceCursor) throw new RemoteError("gateway/bad-request", `session page through seq ${String(request.throughSeq)} is past cursor ${String(sourceCursor)}`, {});
+			if (throughSeq > sourceCursor) throw new RemoteError("gateway/bad-request", `session page through seq ${String(throughSeq)} is past cursor ${String(sourceCursor)}`, {});
 			/* v8 ignore next -- Session and persistence validation guarantee a dense zero-based event prefix. */
-			if (request.throughSeq >= 0 && sourceLog[request.throughSeq]?.seq !== request.throughSeq) throw new RemoteError("gateway/internal", `session log does not contain through seq ${String(request.throughSeq)}`, {});
-			const page = paginate(sourceLog, request.beforeSeq, request.maxMessages ?? DEFAULT_MAX_MESSAGES, request.throughSeq);
+			if (throughSeq >= 0 && sourceLog[throughSeq]?.seq !== throughSeq) throw new RemoteError("gateway/internal", `session log does not contain through seq ${String(throughSeq)}`, {});
+			const page = paginate(sourceLog, beforeSeq, request.maxMessages ?? DEFAULT_MAX_MESSAGES, throughSeq);
 			return {
 				records: pageRecords(page.events),
 				hasMore: page.hasMore
@@ -1253,7 +1261,7 @@ var SessionHistoryController = class {
 		}, { global: true });
 		const disposeCreated = this.ctx.on("session/created", (session) => {
 			if (session.id !== target) return;
-			const suffix = session.events.slice(snapshotCursor === void 0 ? session.firstLiveSeq : snapshotCursor + 1);
+			const suffix = session.snapshotEvents(snapshotCursor === void 0 ? session.firstLiveSeq : SessionLogOffset(snapshotCursor + 1));
 			for (let index = suffix.length - 1; index >= 0; index -= 1) buffered.pushFront(suffix[index]);
 			notify();
 		}, { global: true });
@@ -1276,7 +1284,7 @@ var SessionHistoryController = class {
 				const page = paginate(events, void 0, request.maxMessages ?? DEFAULT_MAX_MESSAGES);
 				yield {
 					type: "snapshot",
-					header: source.header,
+					header: wireHeader(source.header, source.inheritedEventCount),
 					cursor,
 					records: pageRecords(page.events),
 					hasMore: page.hasMore,
@@ -1294,7 +1302,7 @@ var SessionHistoryController = class {
 						throw error;
 					}
 				}
-				let nextSeq = cursor + 1;
+				let nextOffset = SessionLogOffset(cursor + 1);
 				while (!follower.closed && !signal.aborted) {
 					const item = buffered.popFront();
 					if (item === void 0) {
@@ -1303,9 +1311,10 @@ var SessionHistoryController = class {
 						});
 						continue;
 					}
-					if (item.seq < nextSeq) continue;
-					if (item.seq !== nextSeq) throw new RemoteError("gateway/internal", `session event stream skipped seq ${String(nextSeq)}`, {});
-					nextSeq++;
+					const expectedSeq = SessionSeq(nextOffset);
+					if (item.seq < expectedSeq) continue;
+					if (item.seq !== expectedSeq) throw new RemoteError("gateway/internal", `session event stream skipped seq ${String(expectedSeq)}`, {});
+					nextOffset = SessionLogOffset(nextOffset + 1);
 					yield entryFor(item);
 				}
 			} catch (e_2) {
@@ -1333,7 +1342,7 @@ var SessionHistoryController = class {
 				rejectNotFound(address);
 			}
 			try {
-				validateAddress(address, observation.header, observation.projections);
+				validateAddress(address, observation.header, observation.inheritedEventCount, observation.projections);
 			} catch (error) {
 				observation[Symbol.dispose]();
 				throw error;
@@ -1352,8 +1361,8 @@ function projectionBlock(snapshot) {
 	};
 }
 function validatePageRequest(request) {
-	if (!Number.isSafeInteger(request.throughSeq) || request.throughSeq < -1) throw new RemoteError("gateway/bad-request", "throughSeq must be an integer greater than or equal to -1", {});
-	if (request.beforeSeq !== void 0 && (!Number.isSafeInteger(request.beforeSeq) || request.beforeSeq < 0)) throw new RemoteError("gateway/bad-request", "beforeSeq must be a non-negative safe integer", {});
+	if (!Number.isSafeInteger(request.throughSeq) || request.throughSeq < -1 || Object.is(request.throughSeq, -0)) throw new RemoteError("gateway/bad-request", "throughSeq must be an integer greater than or equal to -1", {});
+	if (request.beforeSeq !== void 0 && (!Number.isSafeInteger(request.beforeSeq) || request.beforeSeq < 0 || Object.is(request.beforeSeq, -0))) throw new RemoteError("gateway/bad-request", "beforeSeq must be a non-negative safe integer", {});
 	if (request.maxMessages !== void 0 && (!Number.isSafeInteger(request.maxMessages) || request.maxMessages <= 0)) throw new RemoteError("gateway/bad-request", "maxMessages must be a positive safe integer", {});
 }
 function validateFollowRequest(request) {
@@ -1362,7 +1371,7 @@ function validateFollowRequest(request) {
 function addressId(address) {
 	return address.kind === "session" ? address.sessionId : address.childSessionId;
 }
-function validateAddress(address, header, projections) {
+function validateAddress(address, header, inheritedEventCount, projections) {
 	if (address.kind === "session") {
 		if (header.origin === "subagent") throw new RemoteError("session/agent-busy", "subagent Sessions require their durable parent address", { reason: "use subagent delivery for this child session" });
 		return;
@@ -1374,7 +1383,7 @@ function validateAddress(address, header, projections) {
 		childSessionId: address.childSessionId,
 		reason: "corrupt"
 	});
-	if (identity === void 0 || identity.seq < (header.seedLength ?? 0)) throw new RemoteError("subagent/catalog-diagnostic", "subagent descriptor is unavailable", {
+	if (identity === void 0 || identity.seq < inheritedEventCount) throw new RemoteError("subagent/catalog-diagnostic", "subagent descriptor is unavailable", {
 		parentSessionId: address.parentSessionId,
 		childSessionId: address.childSessionId,
 		reason: "unsupported"
@@ -1389,18 +1398,20 @@ function rejectNotFound(address) {
 	});
 }
 function paginate(events, beforeSeq, maxMessages, throughSeq = events.at(-1)?.seq ?? -1) {
-	const end = Math.min(throughSeq + 1, beforeSeq ?? throughSeq + 1);
+	const end = SessionLogOffset(Math.min(throughSeq + 1, beforeSeq ?? throughSeq + 1));
 	let count = 0;
-	let cut = 0;
+	let cut = SessionLogOffset(0);
 	for (let index = end - 1; index >= 0; index--) {
 		const event = events[index];
 		if (!MESSAGE_TYPES$1.has(event.type) || !isAppendSurfaceEvent(event)) continue;
 		count++;
 		const sources = event.sourceEventSeqs;
 		let groupStart = event.seq;
-		if (sources !== void 0) for (const source of sources) groupStart = Math.min(groupStart, source);
+		if (sources !== void 0) {
+			for (const source of sources) if (source < groupStart) groupStart = source;
+		}
 		if (count >= maxMessages) {
-			cut = groupStart;
+			cut = SessionLogOffset(groupStart);
 			break;
 		}
 	}
@@ -1409,6 +1420,14 @@ function paginate(events, beforeSeq, maxMessages, throughSeq = events.at(-1)?.se
 		hasMore: cut > 0
 	};
 }
+/** Translate logical Session metadata to the unchanged v0 browser wire. */
+function wireHeader(header, inheritedEventCount) {
+	const { isSeeded, ...wire } = header;
+	return {
+		...wire,
+		...isSeeded ? { seedLength: inheritedEventCount } : {}
+	};
+}
 function entryFor(event) {
 	return {
 		type: "event",
@@ -1874,7 +1893,7 @@ var ApiSessionList = class {
 	}
 	projectionsFor(header, session) {
 		try {
-			const block = session === void 0 ? this.ctx.get("sessionProjectionCache")?.cachedSnapshot(header) : this.ctx.sessionProjections.cachedSnapshot(session);
+			const block = session === void 0 ? header.isSeeded ? void 0 : this.ctx.get("sessionProjectionCache")?.cachedSnapshot(header, SessionLogOffset(0)) : this.ctx.sessionProjections.cachedSnapshot(session);
 			return block !== void 0 && Object.keys(block.values).length > 0 ? {
 				asOfSeq: block.asOfSeq,
 				values: block.values
@@ -2657,7 +2676,8 @@ let SessionController = (() => {
 			const attached = this.ctx.sessions.get(sessionId);
 			if (attached !== void 0) return Promise.resolve({
 				meta: attached.header,
-				events: [...attached.events]
+				inheritedEventCount: attached.inheritedEventCount,
+				events: attached.snapshotEvents()
 			});
 			return inspectApiSession(this.ctx, sessionId, signal);
 		}