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

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: 94e8697cd7f5bf75746edd5d691956e680d9b261
+README.zh.md: 0228ca15624413fcd5cb6e17afb8aaf0a28f780a

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.
 
 -----
 

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 重建会话。
 
 -----
 

package/lib/client.js

@@ -671,7 +671,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;
 		}
@@ -740,6 +740,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 +838,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
@@ -1014,6 +1019,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 = 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. */

package/lib/index.js

@@ -7,7 +7,7 @@ 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 { SessionTitleInvalidError } from "@deepseek-ai/dsh-session-title";
 import { canonicalClientTimeZone } from "@deepseek-ai/dsh-util-time";
 import { Deque } from "@deepseek-ai/dsh-deque";
@@ -745,7 +745,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);
@@ -874,21 +874,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) {

package/lib/typert.host.js

@@ -1557,7 +1557,7 @@ export const TYPERT = {
           },
           {
             "name": "RemoteErrorDetailsMap",
-            "declaration": "export interface RemoteErrorDetailsMap {\n    'gateway/bad-request': { readonly issues?: readonly object[]; };\n    'gateway/cancelled': {};\n    'gateway/internal': {};\n    'llm/model-discovery-rejected': { readonly settingsNs: string; readonly baseURL?: string; };\n    'session/not-found': { readonly sessionId: SessionId; };\n    'agent-preset/not-found': { readonly agentPreset: string; readonly available: readonly string[]; };\n    'agent-preset/invalid': { readonly agentPreset: string; readonly reason: string; };\n    'agent-preset/read-only': { readonly agentPreset: string; readonly reason: string; };\n    'agent-preset/locked': { readonly sessionId: SessionId; readonly agentPreset: string; };\n    'workspace/not-found': { readonly workspaceId: WorkspaceId; };\n    'session/model-unavailable': { readonly provider: string; readonly model: string; };\n    'session/conflict': { readonly sessionId: SessionId; readonly requestedCwd: string; readonly existingCwd?: string; };\n    'session/agent-busy': { readonly reason: string; };\n    'session/invalid-time-zone': { readonly value: string; };\n    'session/workspace-attach-failed': { readonly sessionId: SessionId; readonly workspaceId: string; };\n    'agent-preset/conflict': { readonly sessionId: SessionId; readonly requestedPreset: string; readonly existingPreset?: string; };\n    'session/attachment-invalid': { readonly reason: string; };\n    'session/queue-item-not-found': { readonly itemId: MessageId; };\n    'session/steer-unavailable': { readonly itemId: MessageId; };\n    'session/title-invalid': { readonly sessionId: SessionId; };\n    'session/fork-unavailable': { readonly sessionId: SessionId; };\n    'subagent/not-found': { readonly parentSessionId: SessionId; readonly childSessionId: SessionId; };\n    'subagent/catalog-diagnostic': { readonly parentSessionId: SessionId; readonly childSessionId: SessionId; readonly reason: 'corrupt' | 'unsupported' | 'unavailable'; };\n    'subagent/invalid-time-zone': { readonly value: string; };\n    'subagent/parent-unavailable': { readonly parentSessionId: SessionId; };\n    'subagent/not-resumable': { readonly childSessionId: SessionId; };\n    'subagent/unauthorized': { readonly childSessionId: SessionId; };\n    'subagent/attachment-unsupported': { readonly childSessionId: SessionId; readonly reason: string; };\n    'subagent/delivery-unavailable': { readonly childSessionId: SessionId; };\n    'subagent/projections-unavailable': {};\n    'settings/rejected': { readonly ns: string; };\n    'settings/conflict': { readonly ns: string; readonly expected: number; readonly actual: number; };\n    'credential/rejected': { readonly ref: string; };\n    'workspace/invalid-path': { readonly path: string; };\n    'workspace/name-conflict': { readonly name: string; };\n    'workspace/move-invalid': { readonly workspaceId: WorkspaceId; readonly sessionId: SessionId; readonly beforeSessionId?: SessionId; };\n    'directory-picker/unavailable': { readonly capability: string; };\n    'directory-picker/unreadable': { readonly path: string; };\n    'directory-picker/exists': { readonly path: string; };\n    'directory-picker/create-failed': { readonly path: string; };\n}"
+            "declaration": "export interface RemoteErrorDetailsMap {\n    'gateway/bad-request': { readonly issues?: readonly object[]; };\n    'gateway/cancelled': {};\n    'gateway/internal': {};\n    'llm/model-discovery-rejected': { readonly settingsNs: string; readonly baseURL?: string; };\n    'session/not-found': { readonly sessionId: SessionId; };\n    'agent-preset/not-found': { readonly agentPreset: string; readonly available: readonly string[]; };\n    'agent-preset/invalid': { readonly agentPreset: string; readonly reason: string; };\n    'agent-preset/read-only': { readonly agentPreset: string; readonly reason: string; };\n    'agent-preset/locked': { readonly sessionId: SessionId; readonly agentPreset: string; };\n    'workspace/not-found': { readonly workspaceId: WorkspaceId; };\n    'session/model-unavailable': { readonly provider: string; readonly model: string; };\n    'session/conflict': { readonly sessionId: SessionId; readonly requestedCwd: string; readonly existingCwd?: string; };\n    'session/agent-busy': { readonly reason: string; };\n    'session/invalid-time-zone': { readonly value: string; };\n    'session/workspace-attach-failed': { readonly sessionId: SessionId; readonly workspaceId: string; };\n    'agent-preset/conflict': { readonly sessionId: SessionId; readonly requestedPreset: string; readonly existingPreset?: string; };\n    'session/attachment-invalid': { readonly reason: string; };\n    'session/queue-item-not-found': { readonly itemId: MessageId; };\n    'session/steer-unavailable': { readonly itemId: MessageId; };\n    'session/title-invalid': { readonly sessionId: SessionId; };\n    'session/fork-unavailable': { readonly sessionId: SessionId; };\n    'subagent/not-found': { readonly parentSessionId: SessionId; readonly childSessionId: SessionId; };\n    'subagent/catalog-diagnostic': { readonly parentSessionId: SessionId; readonly childSessionId: SessionId; readonly reason: 'corrupt' | 'unsupported' | 'unavailable'; };\n    'subagent/invalid-time-zone': { readonly value: string; };\n    'subagent/parent-unavailable': { readonly parentSessionId: SessionId; };\n    'subagent/not-resumable': { readonly childSessionId: SessionId; };\n    'subagent/unauthorized': { readonly childSessionId: SessionId; };\n    'subagent/attachment-invalid': { readonly reason: string; };\n    'subagent/delivery-unavailable': { readonly childSessionId: SessionId; };\n    'subagent/projections-unavailable': {};\n    'settings/rejected': { readonly ns: string; };\n    'settings/conflict': { readonly ns: string; readonly expected: number; readonly actual: number; };\n    'credential/rejected': { readonly ref: string; };\n    'workspace/invalid-path': { readonly path: string; };\n    'workspace/name-conflict': { readonly name: string; };\n    'workspace/move-invalid': { readonly workspaceId: WorkspaceId; readonly sessionId: SessionId; readonly beforeSessionId?: SessionId; };\n    'directory-picker/unavailable': { readonly capability: string; };\n    'directory-picker/unreadable': { readonly path: string; };\n    'directory-picker/exists': { readonly path: string; };\n    'directory-picker/create-failed': { readonly path: string; };\n}"
           },
           {
             "name": "ReplayEnvelope",

package/lib/types/client/contract/session.d.ts

@@ -28,6 +28,8 @@ export type PendingSubmissionRetirement = {
 };
 /** Input registering one local submission echo ahead of its prompt call. */
 export interface BeginSubmissionInput {
+    /** Delivery mode used with the upcoming prompt. */
+    readonly mode: 'queue' | 'steer';
     /** Prompt text exactly as the upcoming prompt will send it. */
     readonly text: string;
     /** Ordered image previews matching the upcoming prompt's image parts. */
@@ -120,6 +122,15 @@ export interface ISession {
      * @returns completion; failures land in snapshot.openState/loadingOlder.
      */
     loadOlder(): Promise<void>;
+    /**
+     * Page history backwards until the window covers `seq` (inclusive) — the
+     * turn-jump loader. Repeated calls while a jump is paging lower its shared
+     * target and return the in-flight completion; `snapshot.loadingOlder` is
+     * the busy signal for the whole jump.
+     * @param seq - durable event seq the window must reach (a turn's `turn/start` seq).
+     * @returns completion once covered, exhausted, superseded, or failed soft.
+     */
+    loadThrough(seq: number): Promise<void>;
     /**
      * Execute one slash-command line against this session's agent — pure
      * admission semantics (the host executor durably logs the lifecycle).

package/lib/types/client/contract/snapshot.d.ts

@@ -27,6 +27,8 @@ export interface PendingSubmissionImage {
     /** Intrinsic pixel height, when the submitter has probed it. */
     readonly height?: number;
 }
+/** Client surface selected when a local submission begins. */
+export type PendingSubmissionPlacement = 'transcript' | 'queued' | 'steering';
 /**
  * One local prompt-submission echo: inserted synchronously when a submission
  * begins, so the conversation can show the message before serialization,
@@ -36,6 +38,8 @@ export interface PendingSubmissionImage {
 export interface PendingSubmission {
     /** The prompt RPC identity; the durable `user/message` source echoes it as `rpcId`. */
     readonly requestId: SessionRequestId;
+    /** Expected surface until the Host reports the admitted queue or durable occurrence. */
+    readonly placement: PendingSubmissionPlacement;
     /** Client wall-clock ms when the submission began. */
     readonly time: number;
     /** Prompt text exactly as it will be sent (one text block). */

package/lib/types/client/index.d.ts

@@ -13,7 +13,7 @@ export type { BeginSubmissionInput, ISession, PendingSubmissionRetirement, Proje
 export type { ISessions } from './contract/sessions.ts';
 export { MutableSessionEventSource } from './contract/events.ts';
 export type { SessionEventChange, SessionEventLike, SessionEventLikeEntry, SessionEventSource, SessionEventWindow, SessionLiveEventEntry, } from './contract/events.ts';
-export type { OpenState, PendingSubmission, PendingSubmissionImage, PromptError, QueuedMessage, SessionSnapshot, } from './contract/snapshot.ts';
+export type { OpenState, PendingSubmission, PendingSubmissionImage, PendingSubmissionPlacement, PromptError, QueuedMessage, SessionSnapshot, } from './contract/snapshot.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         /** Client Session object layer and Agent scope owner. */

package/lib/types/client/sessions/queue-mirror.js

@@ -1,6 +1,9 @@
 const QUEUE_PREVIEW_CHARS = 200;
+// Image blocks are excluded: queue presentation renders them as thumbnails
+// from `content`, so the text preview covers only what has no visual form.
 function previewOf(content) {
     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);

package/lib/types/client/sessions/session.d.ts

@@ -12,6 +12,8 @@ import type { SessionRemotes } from './remotes.ts';
 import { ProjectionValueStore } from './projection-store.ts';
 /** Messages requested per history page. */
 export declare const PAGE_MESSAGES = 50;
+/** Messages requested per page while a turn jump loops backwards (fewer, larger round trips). */
+export declare const JUMP_PAGE_MESSAGES = 200;
 /** Manager-owned observers of a Session object's local state edges. */
 export interface SessionOptions {
     /** Catalog-discovered address selecting non-activating subagent transport. */
@@ -53,6 +55,10 @@ export declare class Session implements SessionFace {
      *  passes drop all writes once the generation moves on. */
     private openGeneration;
     private loadingOlder;
+    /** Shared low-water target of the running jump loop; null when no jump is paging. */
+    private jumpTargetSeq;
+    /** The running jump loop's completion, shared by retargeting callers. */
+    private jumpPromise;
     /** Authoritative stream-only inbox snapshot; pending work never hits history. */
     private readonly queueMirror;
     private running;
@@ -189,6 +195,8 @@ export declare class Session implements SessionFace {
     open(): Promise<void>;
     /** Page up: pull one earlier page with the window's first seq as beforeSeq and prepend. */
     loadOlder(): Promise<void>;
+    /** Jump loader: page backwards until the window covers seq (see ISession.loadThrough). */
+    loadThrough(seq: number): Promise<void>;
     /** 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. */

package/lib/types/client/sessions/session.js

@@ -9,6 +9,8 @@ import { resolvedClientTimeZone } from "../time-zone.js";
 import { SessionQueueMirror } from "./queue-mirror.js";
 /** Messages requested per history page. */
 export const PAGE_MESSAGES = 50;
+/** Messages requested per page while a turn jump loops backwards (fewer, larger round trips). */
+export const JUMP_PAGE_MESSAGES = 200;
 /**
  * Owns a session's event window, lifecycle state, and observable
  * snapshot. React bindings remain outside this data layer. Features see only
@@ -29,6 +31,10 @@ export class Session {
      *  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;
@@ -125,6 +131,9 @@ export class Session {
         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,
@@ -300,6 +309,58 @@ export class Session {
             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) {
+            // Retarget the running loop to the lowest requested seq.
+            this.jumpTargetSeq = Math.min(this.jumpTargetSeq ?? seq, seq);
+            return this.jumpPromise;
+        }
+        // A plain single-page pull owns the busy flag; the jump does not queue
+        // behind it (the caller retries once it settles) and must leave no
+        // target behind — only the loop's finally clears that field, and no
+        // loop starts here.
+        if (this.loadingOlder)
+            return Promise.resolve();
+        this.jumpTargetSeq = seq;
+        this.loadingOlder = true;
+        this.notifier.markDirty();
+        // Stale-pass guard (the doOpen pattern): a resync mid-loop replaces the
+        // stream generation; this pass then stops instead of paging the new
+        // generation toward its old target.
+        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 === undefined)
+                        return;
+                    const before = this.baseSeq;
+                    await events.prepend({ beforeSeq: this.baseSeq, maxMessages: JUMP_PAGE_MESSAGES });
+                    // No-progress guard: an empty or dropped page that still claims more
+                    // history must end the loop, not spin it.
+                    if (this.baseSeq >= before)
+                        return;
+                }
+            }
+            catch (error) {
+                if (!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. */

package/lib/types/commands.js

@@ -53,7 +53,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
 });
 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 { ReasoningEffortId, createUserMessage, freezeMessage, } from '@deepseek-ai/dsh-llm';
 import { SessionQueryError } from '@deepseek-ai/dsh-session-query';
 import { SessionTitleInvalidError } from '@deepseek-ai/dsh-session-title';
@@ -296,7 +296,7 @@ export class SessionCommandController {
                         throw new RemoteError('session/attachment-invalid', `Model "${current.model}" does not support image input.`, { reason: 'MODEL_DOES_NOT_SUPPORT_IMAGES' });
                     }
                 }
-                const content = await durablePromptContent(this.ctx, request.content);
+                const content = await admitPromptContent(this.ctx.attachments, request.content);
                 const message = createUserMessage({ content, source });
                 if (request.mode === 'steer')
                     agent.steer(message);
@@ -457,17 +457,6 @@ export class SessionCommandController {
         return undefined;
     }
 }
-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 }
-        // admitEncodedImages returns one reference per image part in order.
-        : { type: 'image', attachment: refs[next++] });
-}
 function imageBlockIn(content, match) {
     if (!Array.isArray(content))
         return undefined;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-api-session-controller",
   "description": "Session Remote commands, cold reads, and live control transport",
-  "version": "0.1.2-alpha.2",
+  "version": "0.1.2-alpha.3",
   "publishConfig": {
     "access": "public"
   },
@@ -70,37 +70,37 @@
   "license": "MIT",
   "dependencies": {
     "zod": "^4.4.3",
-    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-deque": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-deque": "^0.1.2-alpha.3",
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-agent-default-model": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-agent-presets": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-api-gateway": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-attachment": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-connection": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-file-reference": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-jobs": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-native-command": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-scope": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session-title": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-skill": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session-projection-cache": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-subagent": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session-query": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-typert-registry": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-util-time": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-util-workspace-path": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-workspace": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.2-alpha.2"
+    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-agent-default-model": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-agent-presets": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-api-gateway": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-attachment": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-client-connection": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-file-reference": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-jobs": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-native-command": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-scope": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session-projection-cache": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session-query": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-skill": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-subagent": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-typert-registry": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-util-time": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session-title": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-util-workspace-path": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-workspace": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.3"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh-jobs": {
@@ -115,37 +115,37 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-agent-default-model": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-agent-presets": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-attachment": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-api-gateway": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-connection": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-store": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-file-reference": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-jobs": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-native-command": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-permission-presets": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-scope": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session-projection-cache": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session-query": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session-title": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-skill": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-storage": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-storage-domain": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-storage-json": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-subagent": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-typert-registry": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-util-crypto": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-util-time": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-util-workspace-path": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-workspace": "^0.1.2-alpha.2"
+    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-agent-default-model": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-agent-presets": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-api-gateway": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-attachment": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-client-connection": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-client-store": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-file-reference": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-jobs": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-scope": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session-projection-cache": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session-query": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session-title": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-skill": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-storage": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-storage-json": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-subagent": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-typert-registry": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-util-time": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-permission-presets": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-native-command": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-util-workspace-path": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-workspace": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-util-crypto": "^0.1.2-alpha.3"
   },
   "scripts": {
     "bundle": "tsdown",