@deepseek-ai/dsh-api-session-controller 0.1.2-alpha.2 → 0.1.2-alpha.4

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: 689635b83bce71e3aecfedf371685a24bede55ab
-README.zh.md: 68da7db60b38aca1b72c991005438ced45b348ea
+README.md: b3d22a340fff6a49270de520a043a1c8dfdbf096
+README.zh.md: 45590a53db17b32cc59f6107957c284b53ee8302

package/README.md

@@ -27,9 +27,9 @@ History pages and follow opening snapshots carry a discriminated `SessionHistory
 
 Each endpoint states its activation policy. List, search, attachment, history pages, log following, skill discovery, and workspace-path opening can inspect persistence without activating an Agent; `canOpenWorkspacePath()` reports native-opening availability without addressing a Session. Queue mutation and cancellation require live state; model, rename, prompt, and file-reference operations may resolve or resume an ordinary Session. Create and fork are the only operations that create a new Agent directly. The skill catalog instead uses a live Agent when present or the recorded preset's standing scope when cold, so listing never starts an Agent.
 
-The Client adapter exposes `SessionEventStream`, a Gateway `RemoteJournalStream` bound to one ordinary or direct-subagent address. It opens follow before the initial page, publishes only contiguous `replace`, `prepend`, and `append` changes, and repairs reconnect or sequence gaps through a tail page. Ordinary records cover `[event.seq, event.seq]`; packed rows cover `[event.seq, event.seq + memberCount - 1]`. A business, persistence, or unresolved continuity failure terminates the stream, while only physical carrier loss selects automatic resumption. `SessionControlStream` is a Gateway `RemoteSnapshotStream`; every generation opens with a complete process-local baseline, so reconnect replaces queue, jobs, and projection state instead of treating transient values as durable events.
+The Client adapter exposes `SessionEventStream`, a Gateway `RemoteJournalStream` bound to one ordinary or direct-subagent address. It opens follow before the initial page, publishes only contiguous `replace`, `prepend`, and `append` changes, and repairs reconnect or sequence gaps through a tail page. Backwards paging has two verbs: `loadOlder()` pulls one 50-message page, and `loadThrough(seq)` — the turn-jump loader — loops 200-message pages until the window covers the target seq, lowering a shared target on repeated calls, stopping on a page that makes no progress, and reporting busy through the same `loadingOlder` snapshot bit. Ordinary records cover `[event.seq, event.seq]`; packed rows cover `[event.seq, event.seq + memberCount - 1]`. A business, persistence, or unresolved continuity failure terminates the stream, while only physical carrier loss selects automatic resumption. `SessionControlStream` is a Gateway `RemoteSnapshotStream`; every generation opens with a complete process-local baseline, so reconnect replaces queue, jobs, and projection state instead of treating transient values as durable events.
 
-The Session object also carries local submission echoes: `session.beginSubmission` inserts one into `SessionSnapshot.pendingSubmissions` synchronously, before the caller serializes and prompts, so a conversation UI can show the message on the submit click's own frame. The prompt's `requestId` is the correlation identity — the Host already echoes it as the durable user source's `rpcId`, and queue occurrences project it as `SessionQueuedItem.rpcId`. An echo retires one animation frame after its durable event or queue occurrence is observed (the delay keeps it renderable until the transcript node is), immediately when its identified prompt fails or is abandoned, and as failed on disposal; each retirement fires the registered `onRetire` callback exactly once. Echoes are Client memory only — reload and reconnect rebuild the conversation from durable events alone.
+The Session object also carries local submission echoes: `session.beginSubmission` inserts one into `SessionSnapshot.pendingSubmissions` synchronously, before the caller serializes and prompts, so a conversation UI can show the message on the submit click's own frame. Session derives each echo's `transcript`, `queued`, or `steering` placement from its current running state and the requested delivery mode, then retains that placement while serialization is in flight. The prompt's `requestId` is the correlation identity: the Host echoes it as the durable user source's `rpcId`, and queue occurrences project it as `SessionQueuedItem.rpcId`. An echo retires one animation frame after its durable event or queue occurrence is observed (the delay keeps it renderable until the replacement is ready), immediately when its identified prompt fails or is abandoned, and as failed on disposal; each retirement fires the registered `onRetire` callback exactly once. Echoes are Client memory only; reload and reconnect rebuild the conversation from durable events alone.
 
 -----
 
@@ -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

@@ -27,9 +27,9 @@ kind: "package-reference"
 
 每个 endpoint 都声明自己的激活策略。列表、搜索、附件、历史页、日志跟随、skill 发现和工作区路径打开可以在不激活 Agent 的情况下检查 persistence；`canOpenWorkspacePath()` 无需指定 Session 即可报告原生打开能力。queue 变更与取消要求 live 状态；模型、重命名、prompt 和文件引用操作可以解析或恢复普通 Session。只有 create 与 fork 会直接创建新 Agent。skill 目录则优先使用已有 live Agent，否则使用所记录 preset 的常驻 scope，因此列表查询绝不会启动 Agent。
 
-Client adapter 提供 `SessionEventStream`，即绑定到一个普通 Session 或 direct subagent address 的 Gateway `RemoteJournalStream`。它在读取首个 page 前打开 follow，只发布连续的 `replace`、`prepend` 和 `append` 变更，并通过 tail page 修复重连或 seq 缺口。普通 record 覆盖 `[event.seq, event.seq]`，packed row 覆盖 `[event.seq, event.seq + memberCount - 1]`。业务、persistence 或无法恢复的连续性错误会终止 stream，只有物理载体断开才触发自动恢复。`SessionControlStream` 是 Gateway `RemoteSnapshotStream`；每代都以完整的进程本地 baseline 开始，因此重连会替换 queue、jobs 和 projection 状态，而不会把瞬态值当作 durable event。
+Client adapter 提供 `SessionEventStream`，即绑定到一个普通 Session 或 direct subagent address 的 Gateway `RemoteJournalStream`。它在读取首个 page 前打开 follow，只发布连续的 `replace`、`prepend` 和 `append` 变更，并通过 tail page 修复重连或 seq 缺口。向后分页有两个动词：`loadOlder()` 拉一页 50 条 message，而 `loadThrough(seq)`——轮次跳转加载器——按 200 条 message 一页循环拉取直到窗口覆盖目标 seq，重复调用会下调共享目标，遇到无进展的页即停止，忙碌状态复用同一个 `loadingOlder` 快照位。普通 record 覆盖 `[event.seq, event.seq]`，packed row 覆盖 `[event.seq, event.seq + memberCount - 1]`。业务、persistence 或无法恢复的连续性错误会终止 stream，只有物理载体断开才触发自动恢复。`SessionControlStream` 是 Gateway `RemoteSnapshotStream`；每代都以完整的进程本地 baseline 开始，因此重连会替换 queue、jobs 和 projection 状态，而不会把瞬态值当作 durable event。
 
-Session 对象还承载本地提交回显：`session.beginSubmission` 在调用方序列化与 prompt 之前，同步把一条回显写入 `SessionSnapshot.pendingSubmissions`，会话 UI 因此能在点击提交的当帧显示消息。prompt 的 `requestId` 就是关联标识，Host 本就把它回显为 durable user source 的 `rpcId`，queue occurrence 也把它投影为 `SessionQueuedItem.rpcId`。回显在观察到其 durable event 或 queue occurrence 后延迟一个动画帧退休（该延迟保证 transcript 节点可渲染之前回显仍在），带标识的 prompt 失败或被放弃时立即退休，销毁时按 failed 退休；每次退休恰好触发一次注册的 `onRetire` 回调。回显只存在于 Client 内存，刷新与重连只从 durable event 重建会话。
+Session 对象还承载本地提交回显：`session.beginSubmission` 在调用方序列化与 prompt 之前，同步把一条回显写入 `SessionSnapshot.pendingSubmissions`，会话 UI 因此能在点击提交的当帧显示消息。Session 根据当前运行状态与请求的投递模式推导每条回显的 `transcript`、`queued` 或 `steering` 位置，并在序列化期间保留该位置。prompt 的 `requestId` 是关联标识：Host 把它回显为 durable user source 的 `rpcId`，queue occurrence 也把它投影为 `SessionQueuedItem.rpcId`。回显在观察到其 durable event 或 queue occurrence 后延迟一个动画帧退休，该延迟保证替代内容就绪前回显仍可渲染；带标识的 prompt 失败或被放弃时立即退休，销毁时按 failed 退休；每次退休恰好触发一次注册的 `onRetire` 回调。回显只存在于 Client 内存；刷新与重连只从 durable event 重建会话。
 
 -----
 
@@ -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.
@@ -671,7 +701,7 @@ window.__ModuleLoader__.load({
 		//#region lib/types/client/sessions/queue-mirror.js
 		const QUEUE_PREVIEW_CHARS = 200;
 		function previewOf(content) {
-			const flat = content.map((block) => block.type === "text" ? block.text : `[${block.type}]`).join(" ").replace(/\s+/g, " ").trim();
+			const flat = content.filter((block) => block.type !== "image").map((block) => block.type === "text" ? block.text : `[${block.type}]`).join(" ").replace(/\s+/g, " ").trim();
 			const chars = Array.from(flat);
 			return chars.length > QUEUE_PREVIEW_CHARS ? `${chars.slice(0, QUEUE_PREVIEW_CHARS).join("")}…` : flat;
 		}
@@ -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;
@@ -740,6 +778,10 @@ window.__ModuleLoader__.load({
 			*  passes drop all writes once the generation moves on. */
 			openGeneration = 0;
 			loadingOlder = false;
+			/** Shared low-water target of the running jump loop; null when no jump is paging. */
+			jumpTargetSeq = null;
+			/** The running jump loop's completion, shared by retargeting callers. */
+			jumpPromise = null;
 			/** Authoritative stream-only inbox snapshot; pending work never hits history. */
 			queueMirror = new SessionQueueMirror();
 			running = false;
@@ -834,6 +876,7 @@ window.__ModuleLoader__.load({
 				const requestId = randomUUID();
 				this.pendingSubmissions = [...this.pendingSubmissions, {
 					requestId,
+					placement: this.running ? input.mode === "steer" ? "steering" : "queued" : "transcript",
 					time: Date.now(),
 					text: input.text,
 					images: input.images
@@ -967,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
@@ -1014,6 +1065,42 @@ window.__ModuleLoader__.load({
 					this.notifier.markDirty();
 				}
 			}
+			/** Jump loader: page backwards until the window covers seq (see ISession.loadThrough). */
+			loadThrough(seq) {
+				if (this.openState !== "open" || !this.hasMore || this.baseSeq <= seq) return Promise.resolve();
+				if (this.jumpPromise !== null) {
+					this.jumpTargetSeq = SessionSeq(Math.min(this.jumpTargetSeq ?? seq, seq));
+					return this.jumpPromise;
+				}
+				if (this.loadingOlder) return Promise.resolve();
+				this.jumpTargetSeq = seq;
+				this.loadingOlder = true;
+				this.notifier.markDirty();
+				const generation = this.openGeneration;
+				this.jumpPromise = (async () => {
+					try {
+						while (this.hasMore && this.jumpTargetSeq !== null && this.baseSeq > this.jumpTargetSeq) {
+							if (generation !== this.openGeneration) return;
+							const events = this.events;
+							if (events === void 0) return;
+							const before = this.baseSeq;
+							await events.prepend({
+								beforeSeq: this.baseSeq,
+								maxMessages: 200
+							});
+							if (this.baseSeq >= before) return;
+						}
+					} catch (error) {
+						if (!(0, _deepseek_ai_dsh_api_gateway_client.isRemoteFailure)(error)) console.error("[session-controller] loadThrough failed:", error);
+					} finally {
+						this.jumpTargetSeq = null;
+						this.jumpPromise = null;
+						this.loadingOlder = false;
+						this.notifier.markDirty();
+					}
+				})();
+				return this.jumpPromise;
+			}
 			/** Rebuild an opened history source after address replacement.
 			*  Invalidates any in-flight open first; queue state belongs to the independently
 			*  reconnecting control stream and remains untouched. */
@@ -1026,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();
 			}
@@ -1170,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);
@@ -1180,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);
@@ -1190,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);
 			}
@@ -1315,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 };
 		}
@@ -1648,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";
@@ -1799,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;
 				}
@@ -1819,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();
@@ -1835,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);
@@ -2359,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

@@ -7,11 +7,11 @@ import { installModelSelection } from "@deepseek-ai/dsh-agent";
 import { SessionQueryError } from "@deepseek-ai/dsh-session-query";
 import { randomUUID } from "node:crypto";
 import { brandString } from "@deepseek-ai/dsh-brand";
-import { AttachmentError, admitEncodedImages } from "@deepseek-ai/dsh-attachment";
+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: {
@@ -745,7 +751,7 @@ var SessionCommandController = class {
 					if (model.inputModalities !== void 0 && !model.inputModalities.includes("image")) throw new RemoteError("session/attachment-invalid", `Model "${current.model}" does not support image input.`, { reason: "MODEL_DOES_NOT_SUPPORT_IMAGES" });
 				}
 				const message = createUserMessage({
-					content: await durablePromptContent(this.ctx, request.content),
+					content: await admitPromptContent(this.ctx.attachments, request.content),
 					source
 				});
 				if (request.mode === "steer") agent.steer(message);
@@ -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 {
@@ -874,21 +880,6 @@ var SessionCommandController = class {
 		}
 	}
 };
-async function durablePromptContent(ctx, content) {
-	if (content.every((part) => part.type === "text")) return content.map((part) => ({
-		type: "text",
-		text: part.text
-	}));
-	const refs = await admitEncodedImages(ctx.attachments, content.filter((part) => part.type === "image"));
-	let next = 0;
-	return content.map((part) => part.type === "text" ? {
-		type: "text",
-		text: part.text
-	} : {
-		type: "image",
-		attachment: refs[next++]
-	});
-}
 function imageBlockIn(content, match) {
 	if (!Array.isArray(content)) return void 0;
 	for (const value of content) {
@@ -1218,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
@@ -1268,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 });
@@ -1291,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,
@@ -1309,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) {
@@ -1318,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) {
@@ -1348,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;
@@ -1367,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) {
@@ -1377,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;
@@ -1389,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"
@@ -1404,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;
 		}
 	}
@@ -1424,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",
@@ -1889,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
@@ -2672,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);
 		}