@deepseek-ai/dsh-api-session-controller 0.1.2-rc.1 → 0.1.5-alpha.1

package/lib/index.js

@@ -1,23 +1,26 @@
 import z from "@deepseek-ai/schemastery";
-import { ReasoningEffortId, createUserMessage, errorChain, freezeMessage } from "@deepseek-ai/dsh-llm";
+import { AssistantStreamAccumulator, ReasoningEffortId, assistantStreamChunks, createUserMessage, errorChain, freezeMessage } from "@deepseek-ai/dsh-llm";
 import { canOpenNativePath, openNativePath } from "@deepseek-ai/dsh-native-command";
 import { Remote, RemoteError, TypertRemoteService, remoteErrorOf } from "@deepseek-ai/dsh-typert-protocol";
-import { mkdir, stat } from "node:fs/promises";
+import { mkdir } from "node:fs/promises";
 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, admitPromptContent } from "@deepseek-ai/dsh-attachment";
+import { AttachmentError } 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 { assertNever } from "@deepseek-ai/dsh-util-values";
 import { Deque } from "@deepseek-ai/dsh-deque";
-import { isChunkRow, packChunkRuns } from "@deepseek-ai/dsh-session/chunk-rows";
 import { z as z$1 } from "zod";
 import { isUserInvocable } from "@deepseek-ai/dsh-skill";
+import { isAbsolute } from "node:path";
+import { FsError } from "@deepseek-ai/dsh-fs";
+import mime from "mime-types";
 //#region lib/types/agent.js
 /** Agent activation, composition, and model-selection policy owned by API Session. */
-var __addDisposableResource$5 = function(env, value, async) {
+var __addDisposableResource$4 = function(env, value, async) {
 	if (value !== null && value !== void 0) {
 		if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
 		var dispose, inner;
@@ -46,7 +49,7 @@ var __addDisposableResource$5 = function(env, value, async) {
 	} else if (async) env.stack.push({ async: true });
 	return value;
 };
-var __disposeResources$5 = (function(SuppressedError) {
+var __disposeResources$4 = (function(SuppressedError) {
 	return function(env) {
 		function fail(e) {
 			env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
@@ -147,7 +150,7 @@ async function inspectApiSession(ctx, sessionId, signal) {
 			hasError: false
 		};
 		try {
-			const observation = __addDisposableResource$5(env_1, await ctx.sessionQuery.observeSession(sessionId, {
+			const observation = __addDisposableResource$4(env_1, await ctx.sessionQuery.observeSession(sessionId, {
 				...signal === void 0 ? {} : { signal },
 				projectionMode: "none"
 			}), false);
@@ -161,7 +164,7 @@ async function inspectApiSession(ctx, sessionId, signal) {
 			env_1.error = e_1;
 			env_1.hasError = true;
 		} finally {
-			__disposeResources$5(env_1);
+			__disposeResources$4(env_1);
 		}
 	} catch (error) {
 		if (error instanceof SessionQueryError && error.code === "SESSION_QUERY_SESSION_NOT_FOUND") throw new ApiSessionNotFound(`session "${sessionId}" not found`);
@@ -349,14 +352,14 @@ var ApiSessionAgentController = class {
 	*/
 	async composeAgent(presetId) {
 		const presets = this.ctx.get("agentPresets");
-		if (presets === void 0) return { setup: (agentCtx) => {
-			this.installSelection(agentCtx);
+		if (presets === void 0) return { setup: (_agentCtx, agent) => {
+			this.installSelection(agent);
 		} };
 		const resolvedId = (await presets.resolve(presetId)).id;
 		return {
 			agentPreset: resolvedId,
-			setup: async (agentCtx) => {
-				this.installSelection(agentCtx);
+			setup: async (agentCtx, agent) => {
+				this.installSelection(agent);
 				await presets.mount(agentCtx, resolvedId);
 			}
 		};
@@ -375,13 +378,13 @@ var ApiSessionAgentController = class {
 				hasError: false
 			};
 			try {
-				const observation = __addDisposableResource$5(env_2, await this.ctx.sessionQuery.observeSession(sessionId), false);
+				const observation = __addDisposableResource$4(env_2, await this.ctx.sessionQuery.observeSession(sessionId), false);
 				return await this.resumeObserved(sessionId, observation);
 			} catch (e_2) {
 				env_2.error = e_2;
 				env_2.hasError = true;
 			} finally {
-				__disposeResources$5(env_2);
+				__disposeResources$4(env_2);
 			}
 		} catch (error) {
 			if (error instanceof SessionQueryError && error.code === "SESSION_QUERY_SESSION_NOT_FOUND") throw new ApiSessionNotFound(`session "${sessionId}" not found`);
@@ -413,7 +416,7 @@ var ApiSessionAgentController = class {
 				hasError: false
 			};
 			try {
-				const observation = __addDisposableResource$5(env_3, await this.ctx.sessionQuery.observeSession(sessionId), false);
+				const observation = __addDisposableResource$4(env_3, await this.ctx.sessionQuery.observeSession(sessionId), false);
 				if (hasApiSessionSubagentOwner(this.ctx, { header: observation.header }, void 0)) throw new ApiSessionSubagentOwnership(sessionId);
 				if (observation.header.cwd !== cwd) throw new ApiSessionCwdConflict(sessionId, cwd, observation.header.cwd);
 				const storedPreset = this.presetForObservation(observation);
@@ -428,7 +431,7 @@ var ApiSessionAgentController = class {
 				env_3.error = e_3;
 				env_3.hasError = true;
 			} finally {
-				__disposeResources$5(env_3);
+				__disposeResources$4(env_3);
 			}
 		} catch (error) {
 			if (!(error instanceof SessionQueryError) || error.code !== "SESSION_QUERY_SESSION_NOT_FOUND") throw error;
@@ -456,9 +459,7 @@ var ApiSessionAgentController = class {
 			model
 		};
 	}
-	installSelection(agentCtx) {
-		const agent = agentCtx.agent;
-		if (agent === void 0) throw new Error("api-session: Agent setup has no scoped Agent");
+	installSelection(agent) {
 		this.selectionFor(agent);
 	}
 	/**
@@ -485,7 +486,7 @@ function agentModelSelection(selection) {
 //#endregion
 //#region lib/types/commands.js
 /** Session commands whose activation policy is explicit at each Remote method. */
-var __addDisposableResource$4 = function(env, value, async) {
+var __addDisposableResource$3 = function(env, value, async) {
 	if (value !== null && value !== void 0) {
 		if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
 		var dispose, inner;
@@ -514,7 +515,7 @@ var __addDisposableResource$4 = function(env, value, async) {
 	} else if (async) env.stack.push({ async: true });
 	return value;
 };
-var __disposeResources$4 = (function(SuppressedError) {
+var __disposeResources$3 = (function(SuppressedError) {
 	return function(env) {
 		function fail(e) {
 			env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
@@ -543,6 +544,9 @@ var __disposeResources$4 = (function(SuppressedError) {
 	var e = new Error(message);
 	return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
+function hasPromptContent(content) {
+	return content.some((part) => part.type !== "text" || part.text.trim().length > 0);
+}
 /** Implements Session business commands delegated by the Session Controller Remote service. */
 var SessionCommandController = class {
 	ctx;
@@ -672,7 +676,7 @@ var SessionCommandController = class {
 				if (error instanceof SessionQueryError && error.code === "SESSION_QUERY_SESSION_NOT_FOUND") throw new RemoteError("session/not-found", `session "${request.sessionId}" not found`, { sessionId: request.sessionId });
 				throw new RemoteError("gateway/internal", `fork source unavailable for session "${request.sessionId}": ${String(error)}`, {});
 			}
-			const source = __addDisposableResource$4(env_1, observed, false);
+			const source = __addDisposableResource$3(env_1, observed, false);
 			const lastSeq = source.events.at(-1)?.seq ?? -1;
 			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 });
@@ -720,18 +724,20 @@ var SessionCommandController = class {
 			env_1.error = e_1;
 			env_1.hasError = true;
 		} finally {
-			__disposeResources$4(env_1);
+			__disposeResources$3(env_1);
 		}
 	}
 	/**
-	* Admit one browser prompt after explicit Agent resume and image validation.
+	* Reject empty content, then admit one prompt after Agent and attachment validation.
 	* @param request - Session identity, prompt content, source metadata, and delivery mode.
 	* @returns acknowledgement that the Agent accepted the prompt.
 	*/
 	async prompt(request) {
+		if (!hasPromptContent(request.content)) throw new RemoteError("gateway/bad-request", "prompt content must include non-whitespace text or an attachment", {});
 		const clientTimeZone = request.clientTimeZone === void 0 ? void 0 : canonicalClientTimeZone(request.clientTimeZone);
 		if (request.clientTimeZone !== void 0 && clientTimeZone === void 0) throw new RemoteError("session/invalid-time-zone", "clientTimeZone must be UTC or a valid IANA Area/Location name", { value: request.clientTimeZone });
 		const agent = await this.resolveAgent(request.sessionId);
+		if (hasPromptRequest(agent, request.requestId)) return { accepted: true };
 		const selection = this.agents.selectionFor(agent).current;
 		if (!routeServed(this.ctx, selection.provider)) throw new RemoteError("session/model-unavailable", `no adapter serves provider "${selection.provider}"; select a model for this session`, {
 			provider: selection.provider,
@@ -745,17 +751,33 @@ var SessionCommandController = class {
 		const hasImage = request.content.some((part) => part.type === "image");
 		const admit = async () => {
 			try {
-				if (hasImage) {
-					const current = this.agents.selectionFor(agent).current;
-					const model = await this.ctx.llm.resolveModelInfo(current.provider, current.model);
-					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 env_2 = {
+					stack: [],
+					error: void 0,
+					hasError: false
+				};
+				try {
+					if (hasImage) {
+						const current = this.agents.selectionFor(agent).current;
+						const model = await this.ctx.llm.resolveModelInfo(current.provider, current.model);
+						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 admission = resolvePromptFileReceipts(request.content, (receiptId) => this.ctx.fileUploads.resolve(agent, receiptId));
+					const message = createUserMessage({
+						content: await this.ctx.attachments.admitPromptContent(admission.content),
+						source
+					});
+					if (this.ctx.agents.get(agent.id) !== agent) throw new RemoteError("session/not-found", `session "${agent.id}" was disposed during prompt admission`, { sessionId: agent.id });
+					const binding = __addDisposableResource$3(env_2, this.ctx.fileUploads.bindPrompt(agent, admission.receiptIds, request.requestId), false);
+					if (request.mode === "steer") agent.steer(message);
+					else agent.followup(message);
+					binding.commit();
+				} catch (e_2) {
+					env_2.error = e_2;
+					env_2.hasError = true;
+				} finally {
+					__disposeResources$3(env_2);
 				}
-				const message = createUserMessage({
-					content: await admitPromptContent(this.ctx.attachments, request.content),
-					source
-				});
-				if (request.mode === "steer") agent.steer(message);
-				else agent.followup(message);
 			} catch (error) {
 				if (remoteErrorOf(error) !== void 0) throw error;
 				if (error instanceof AttachmentError) throw new RemoteError("session/attachment-invalid", error.message, { reason: error.code });
@@ -797,10 +819,16 @@ var SessionCommandController = class {
 	* @returns acknowledgement that the queue mutation was applied.
 	*/
 	updateQueue(request) {
-		if (request.action.kind === "edit" && request.action.content.some((block) => block.type !== "text")) throw new RemoteError("session/attachment-invalid", "queue edits accept text content only", { reason: "QUEUE_EDIT_NON_TEXT" });
+		if (request.action.kind === "edit") {
+			if (request.action.content.some((block) => block.type !== "text")) throw new RemoteError("session/attachment-invalid", "queue edits accept text content only", { reason: "QUEUE_EDIT_NON_TEXT" });
+			if (!hasPromptContent(request.action.content)) throw new RemoteError("gateway/bad-request", "queue edit content must include non-whitespace text", {});
+		}
 		const agent = this.ctx.agents.get(request.sessionId);
-		if (agent !== void 0 && hasApiSessionSubagentOwner(this.ctx, agent.session, agent)) throw apiSessionSubagentOwnershipError(request.sessionId);
 		if (agent === void 0) throw new RemoteError("session/queue-item-not-found", "queued item is no longer pending", { itemId: request.itemId });
+		if (hasApiSessionSubagentOwner(this.ctx, agent.session, agent)) {
+			const identity = this.ctx.sessionProjections.snapshot(agent.session, ["subagent"]).values.subagent;
+			if (identity?.mode !== "continuable" || !agent.session.isOwnSeq(identity.seq)) throw apiSessionSubagentOwnershipError(request.sessionId);
+		}
 		const nextTurn = agent.inbox.nextTurn.find((message) => message.id === request.itemId);
 		const nextStep = agent.inbox.nextStep.find((message) => message.id === request.itemId);
 		const located = nextTurn === void 0 ? nextStep === void 0 ? void 0 : {
@@ -813,13 +841,25 @@ var SessionCommandController = class {
 		if (located === void 0) throw new RemoteError("session/queue-item-not-found", "queued item is no longer pending", { itemId: request.itemId });
 		const { target, message } = located;
 		if (request.action.kind === "steer" && (target !== "next-turn" || agent.status !== "running")) throw new RemoteError("session/steer-unavailable", "current turn no longer accepts steering", { itemId: request.itemId });
-		if (request.action.kind === "edit") agent.inbox.replace(request.itemId, freezeMessage({
-			...message,
-			content: [...request.action.content]
-		}));
-		else {
-			agent.inbox.remove(request.itemId);
-			if (request.action.kind === "steer") agent.steer(message);
+		switch (request.action.kind) {
+			case "edit":
+				agent.inbox.replace(request.itemId, freezeMessage({
+					...message,
+					content: [...request.action.content]
+				}));
+				break;
+			case "remove": {
+				agent.inbox.remove(request.itemId);
+				const source = message.source;
+				if (source.kind === "user" && "rpcId" in source) this.ctx.fileUploads.retirePrompt(agent, source.rpcId);
+				break;
+			}
+			case "steer":
+				agent.inbox.remove(request.itemId);
+				agent.steer(message);
+				break;
+			/* v8 ignore next 2 -- closed-union exhaustiveness guard */
+			default: assertNever(request.action, "queue action");
 		}
 		return { accepted: true };
 	}
@@ -880,6 +920,34 @@ var SessionCommandController = class {
 		}
 	}
 };
+function resolvePromptFileReceipts(content, stagedFile) {
+	const receiptIds = /* @__PURE__ */ new Set();
+	return {
+		content: content.map((part) => {
+			if (part.type !== "file") return part;
+			const attachment = stagedFile(part.receiptId);
+			if (attachment === void 0) throw new RemoteError("session/attachment-invalid", "File was not uploaded for this session.", { reason: "FILE_NOT_STAGED" });
+			receiptIds.add(part.receiptId);
+			return {
+				type: "file",
+				attachment
+			};
+		}),
+		receiptIds: [...receiptIds]
+	};
+}
+function hasPromptRequest(agent, requestId) {
+	const matches = (message) => {
+		const source = message.source;
+		return source.kind === "user" && "rpcId" in source && source.rpcId === requestId;
+	};
+	if (agent.inbox.nextTurn.some(matches) || agent.inbox.nextStep.some(matches)) return true;
+	return agent.session.snapshotEvents().some((event) => {
+		if (event.type !== "user/message") return false;
+		const source = event.data.source;
+		return source.kind === "user" && "rpcId" in source && source.rpcId === requestId;
+	});
+}
 function imageBlockIn(content, match) {
 	if (!Array.isArray(content)) return void 0;
 	for (const value of content) {
@@ -905,7 +973,10 @@ function imageInEvent(event, match) {
 		const found = imageBlockIn(inserted.content, match);
 		if (found !== void 0) return found;
 	}
-	return event.type === "assistant/chunk" && data.chunk?.type === "block-end" ? imageBlockIn([data.chunk.block], match) : void 0;
+	if (event.type === "assistant/message" || event.type === "assistant/attempt") for (const chunk of assistantStreamChunks(event.data.stream, "block-end")) {
+		const found = imageBlockIn([chunk.block], match);
+		if (found !== void 0) return found;
+	}
 }
 function referencedImage(events, attachmentId) {
 	for (const event of events) {
@@ -926,9 +997,6 @@ var SessionControlController = class {
 	/** @param ctx - Host context carrying live Agent, projection, and jobs services. */
 	constructor(ctx) {
 		this.ctx = ctx;
-		ctx.on("session/event", (session, event) => {
-			this.onSessionEvent(session, event);
-		});
 		ctx.sessionProjections.onChanged((session, key, value, seq) => {
 			this.broadcast({
 				type: "projection",
@@ -937,6 +1005,13 @@ var SessionControlController = class {
 				value,
 				seq
 			});
+			if (key !== "inbox") return;
+			if (this.ctx.agents.get(session.id)?.session !== session) return;
+			this.broadcast({
+				type: "queue",
+				sessionId: session.id,
+				items: queueItemsFromInbox(value)
+			});
 		});
 		ctx.inject(["jobs"], (jobsCtx) => {
 			jobsCtx.jobs.onJobsChanged((owner) => {
@@ -1002,16 +1077,6 @@ var SessionControlController = class {
 		}
 		return blocks;
 	}
-	onSessionEvent(session, event) {
-		if (event.type !== "agent/inbox/spliced") return;
-		const agent = this.ctx.agents.get(session.id);
-		if (agent?.session !== session) return;
-		this.broadcast({
-			type: "queue",
-			sessionId: session.id,
-			items: queueItems(agent, event.data)
-		});
-	}
 	onJobsChanged(owner) {
 		if (owner !== void 0) {
 			this.broadcast({
@@ -1076,12 +1141,14 @@ var ControlQueue = class {
 		}
 	}
 };
-function queueItems(agent, splice) {
-	const project = (target) => {
-		const messages = target === "next-turn" ? agent.inbox.nextTurn : agent.inbox.nextStep;
-		return splice?.target === target ? messages.toSpliced(splice.start, splice.removedCount ?? 0, ...splice.inserted) : messages;
-	};
-	return [...project("next-turn").map((message) => ({
+function queueItems(agent) {
+	return queueItemsFromInbox({
+		"next-turn": agent.inbox.nextTurn,
+		"next-step": agent.inbox.nextStep
+	});
+}
+function queueItemsFromInbox(inbox) {
+	return [...inbox["next-turn"].map((message) => ({
 		id: message.id,
 		placement: "queued",
 		...promptRpcId(message),
@@ -1089,7 +1156,7 @@ function queueItems(agent, splice) {
 			id: message.id,
 			content: message.content
 		}
-	})), ...project("next-step").map((message) => ({
+	})), ...inbox["next-step"].map((message) => ({
 		id: message.id,
 		placement: message.source.kind === "user" ? "steering" : "context",
 		...promptRpcId(message),
@@ -1116,9 +1183,90 @@ function jobView(job) {
 	};
 }
 //#endregion
+//#region lib/types/assistant-stream.js
+/** Process-local assistant state retained for reconnecting Web followers. */
+const EMPTY_BASELINE = { revision: 0 };
+/**
+* Folds dense Agent frames and materializes one shared immutable reconnect
+* baseline per accepted revision.
+*/
+var SessionAssistantStreamAccumulator = class {
+	activeAttempt;
+	revision = 0;
+	snapshotValue = EMPTY_BASELINE;
+	dirty = false;
+	/**
+	* Fold one trusted frame from the current attached Agent lifecycle.
+	* @param frame - next dense process-local Assistant frame.
+	* @param durableCursor - last committed Session seq when this frame was observed.
+	*/
+	accept(frame, durableCursor) {
+		if (frame.type === "start" && frame.revision === 1 && this.revision !== 0) {
+			this.activeAttempt = void 0;
+			this.revision = 0;
+		}
+		if (frame.revision !== this.revision + 1) {
+			this.activeAttempt = void 0;
+			this.revision = frame.revision;
+			this.dirty = true;
+			return;
+		}
+		this.revision = frame.revision;
+		switch (frame.type) {
+			case "start":
+				this.activeAttempt = {
+					attemptId: frame.attemptId,
+					startedAfterSeq: durableCursor,
+					turn: frame.turn,
+					step: frame.step,
+					stream: new AssistantStreamAccumulator(),
+					nextIndex: 0
+				};
+				break;
+			case "chunk": {
+				const attempt = this.activeAttempt;
+				if (attempt === void 0 || attempt.attemptId !== frame.attemptId || frame.index !== attempt.nextIndex) {
+					this.activeAttempt = void 0;
+					break;
+				}
+				attempt.stream.push({
+					time: frame.time,
+					chunk: frame.chunk
+				});
+				attempt.nextIndex += 1;
+				break;
+			}
+			case "end":
+				this.activeAttempt = void 0;
+				break;
+		}
+		this.dirty = true;
+	}
+	/**
+	* Read the cached reconnect baseline, materializing it after a state change.
+	* @returns the identity-stable baseline for the latest accepted revision.
+	*/
+	snapshot() {
+		if (!this.dirty) return this.snapshotValue;
+		this.snapshotValue = {
+			revision: this.revision,
+			...this.activeAttempt === void 0 ? {} : { activeAttempt: {
+				attemptId: this.activeAttempt.attemptId,
+				startedAfterSeq: this.activeAttempt.startedAfterSeq,
+				turn: this.activeAttempt.turn,
+				step: this.activeAttempt.step,
+				nextIndex: this.activeAttempt.nextIndex,
+				stream: this.activeAttempt.stream.snapshot()
+			} }
+		};
+		this.dirty = false;
+		return this.snapshotValue;
+	}
+};
+//#endregion
 //#region lib/types/history.js
 /** Cold Session history pagination and live-event source. */
-var __addDisposableResource$3 = function(env, value, async) {
+var __addDisposableResource$2 = function(env, value, async) {
 	if (value !== null && value !== void 0) {
 		if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
 		var dispose, inner;
@@ -1147,7 +1295,7 @@ var __addDisposableResource$3 = function(env, value, async) {
 	} else if (async) env.stack.push({ async: true });
 	return value;
 };
-var __disposeResources$3 = (function(SuppressedError) {
+var __disposeResources$2 = (function(SuppressedError) {
 	return function(env) {
 		function fail(e) {
 			env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
@@ -1183,6 +1331,7 @@ var SessionHistoryController = class {
 	ctx;
 	promote;
 	closeFollowers = /* @__PURE__ */ new Set();
+	assistantStreams = /* @__PURE__ */ new Map();
 	/**
 	* @param ctx - Host context carrying Session query and projection services.
 	* @param promote - starts ordinary Session activation after snapshot delivery.
@@ -1190,6 +1339,17 @@ var SessionHistoryController = class {
 	constructor(ctx, promote) {
 		this.ctx = ctx;
 		this.promote = promote;
+		ctx.on("agent/assistant-stream", ({ agent, frame }) => {
+			let stream = this.assistantStreams.get(agent.session.id);
+			if (stream === void 0) {
+				stream = new SessionAssistantStreamAccumulator();
+				this.assistantStreams.set(agent.session.id, stream);
+			}
+			stream.accept(frame, cursorBeforeNext(agent.session.seq));
+		}, { global: true });
+		ctx.on("agent/disposed", ({ agent }) => {
+			this.assistantStreams.delete(agent.session.id);
+		}, { global: true });
 		ctx.effect(() => () => {
 			for (const close of this.closeFollowers) close();
 			this.closeFollowers.clear();
@@ -1211,7 +1371,7 @@ var SessionHistoryController = class {
 			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);
+			const source = __addDisposableResource$2(env_1, await this.sourceFor(request.address, signal, false), false);
 			signal.throwIfAborted();
 			const sourceLog = source.events;
 			const sourceCursor = sourceLog.at(-1)?.seq ?? -1;
@@ -1227,14 +1387,14 @@ var SessionHistoryController = class {
 			env_1.error = e_1;
 			env_1.hasError = true;
 		} finally {
-			__disposeResources$3(env_1);
+			__disposeResources$2(env_1);
 		}
 	}
 	/**
 	* Follow events appended after an initial cursor on one durable address.
 	* @param request - durable address and last committed sequence already held by the caller.
 	* @param signal - stream cancellation owned by the Remote carrier.
-	* @returns a complete opening snapshot followed by gap-free event frames.
+	* @returns a complete opening snapshot followed by gap-free durable events and opted-in assistant frames.
 	*/
 	async *follow(request, signal) {
 		validateFollowRequest(request);
@@ -1242,6 +1402,7 @@ var SessionHistoryController = class {
 		const target = addressId(address);
 		const buffered = new Deque();
 		let snapshotCursor;
+		let assistantStreamOrdinal = 0;
 		let wake;
 		const notify = () => {
 			const resume = wake;
@@ -1256,13 +1417,28 @@ var SessionHistoryController = class {
 		this.closeFollowers.add(close);
 		const disposeEvent = this.ctx.on("session/event", (session, event) => {
 			if (session.id !== target) return;
-			buffered.pushBack(event);
+			buffered.pushBack({
+				type: "event",
+				event
+			});
 			notify();
 		}, { global: true });
 		const disposeCreated = this.ctx.on("session/created", (session) => {
 			if (session.id !== target) return;
 			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]);
+			for (let index = suffix.length - 1; index >= 0; index -= 1) buffered.pushFront({
+				type: "event",
+				event: suffix[index]
+			});
+			notify();
+		}, { global: true });
+		const disposeAssistantStream = request.assistantStream !== true ? void 0 : this.ctx.on("agent/assistant-stream", ({ agent, frame }) => {
+			if (agent.session.id !== target) return;
+			buffered.pushBack({
+				type: "assistant-stream",
+				frame: wireAssistantStreamFrame(frame, cursorBeforeNext(agent.session.seq)),
+				ordinal: ++assistantStreamOrdinal
+			});
 			notify();
 		}, { global: true });
 		const onAbort = () => {
@@ -1276,22 +1452,25 @@ var SessionHistoryController = class {
 				hasError: false
 			};
 			try {
-				const source = __addDisposableResource$3(env_2, await this.sourceFor(address, signal, true), false);
+				const source = __addDisposableResource$2(env_2, await this.sourceFor(address, signal, true), false);
 				const events = source.events;
 				signal.throwIfAborted();
 				const cursor = source.cursor;
 				snapshotCursor = cursor;
 				const page = paginate(events, void 0, request.maxMessages ?? DEFAULT_MAX_MESSAGES);
+				const assistantStream = request.assistantStream === true ? this.assistantStreams.get(target)?.snapshot() ?? { revision: 0 } : void 0;
+				const assistantStreamOrdinalCut = assistantStreamOrdinal;
 				yield {
 					type: "snapshot",
-					header: wireHeader(source.header, source.inheritedEventCount),
+					header: wireHeader(source.header),
 					cursor,
 					records: pageRecords(page.events),
 					hasMore: page.hasMore,
 					projections: source.projections === void 0 ? {
 						asOfSeq: cursor,
 						values: {}
-					} : projectionBlock(source.projections)
+					} : projectionBlock(source.projections),
+					...assistantStream === void 0 ? {} : { assistantStream }
 				};
 				if (address.kind === "session" && source.source === "prepared") {
 					const promotion = source.retain();
@@ -1311,23 +1490,31 @@ var SessionHistoryController = class {
 						});
 						continue;
 					}
+					if (item.type === "assistant-stream") {
+						if (item.ordinal > assistantStreamOrdinalCut) yield {
+							type: "assistant-stream",
+							frame: item.frame
+						};
+						continue;
+					}
 					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)}`, {});
+					if (item.event.seq < expectedSeq) continue;
+					if (item.event.seq !== expectedSeq) throw new RemoteError("gateway/internal", `session event stream skipped seq ${String(expectedSeq)}`, {});
 					nextOffset = SessionLogOffset(nextOffset + 1);
-					yield entryFor(item);
+					yield entryFor(item.event);
 				}
 			} catch (e_2) {
 				env_2.error = e_2;
 				env_2.hasError = true;
 			} finally {
-				__disposeResources$3(env_2);
+				__disposeResources$2(env_2);
 			}
 		} finally {
 			this.closeFollowers.delete(close);
 			signal.removeEventListener("abort", onAbort);
 			disposeCreated();
 			disposeEvent();
+			disposeAssistantStream?.();
 		}
 	}
 	async sourceFor(address, signal, withProjections) {
@@ -1354,6 +1541,20 @@ var SessionHistoryController = class {
 		}
 	}
 };
+function cursorBeforeNext(nextSeq) {
+	return nextSeq === 0 ? -1 : SessionSeq(nextSeq - 1);
+}
+function wireAssistantStreamFrame(frame, durableCursor) {
+	if (frame.type === "start") return {
+		...frame,
+		startedAfterSeq: durableCursor
+	};
+	if (frame.type === "end") return frame;
+	return {
+		...frame,
+		chunk: frame.chunk
+	};
+}
 function projectionBlock(snapshot) {
 	return {
 		asOfSeq: snapshot.asOfSeq,
@@ -1420,13 +1621,9 @@ 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 } : {}
-	};
+/** Translate current logical Session metadata to the browser wire. */
+function wireHeader(header) {
+	return { ...header };
 }
 function entryFor(event) {
 	return {
@@ -1434,40 +1631,9 @@ function entryFor(event) {
 		event
 	};
 }
-function chunkEntryFor(row) {
-	switch (row.type) {
-		case "text-chunks": return {
-			type: "chunks",
-			event: {
-				type: "chunkrow/text-chunks",
-				seq: row.seq0,
-				time: row.time0,
-				data: row.data
-			}
-		};
-		case "reasoning-chunks": return {
-			type: "chunks",
-			event: {
-				type: "chunkrow/reasoning-chunks",
-				seq: row.seq0,
-				time: row.time0,
-				data: row.data
-			}
-		};
-		case "tool-call-chunks": return {
-			type: "chunks",
-			event: {
-				type: "chunkrow/tool-call-chunks",
-				seq: row.seq0,
-				time: row.time0,
-				data: row.data
-			}
-		};
-	}
-}
 /** Encode one bounded logical page without changing its pagination cut. */
 function pageRecords(events) {
-	return packChunkRuns(events).map((record) => isChunkRow(record) ? chunkEntryFor(record) : entryFor(record));
+	return events.map(entryFor);
 }
 //#endregion
 //#region lib/types/file-references.js
@@ -1558,67 +1724,6 @@ let SessionFileReferences = (() => {
 //#endregion
 //#region lib/types/list.js
 /** Cold-safe Session list and search projection. */
-var __addDisposableResource$2 = function(env, value, async) {
-	if (value !== null && value !== void 0) {
-		if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
-		var dispose, inner;
-		if (async) {
-			if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
-			dispose = value[Symbol.asyncDispose];
-		}
-		if (dispose === void 0) {
-			if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
-			dispose = value[Symbol.dispose];
-			if (async) inner = dispose;
-		}
-		if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
-		if (inner) dispose = function() {
-			try {
-				inner.call(this);
-			} catch (e) {
-				return Promise.reject(e);
-			}
-		};
-		env.stack.push({
-			value,
-			dispose,
-			async
-		});
-	} else if (async) env.stack.push({ async: true });
-	return value;
-};
-var __disposeResources$2 = (function(SuppressedError) {
-	return function(env) {
-		function fail(e) {
-			env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
-			env.hasError = true;
-		}
-		var r, s = 0;
-		function next() {
-			while (r = env.stack.pop()) try {
-				if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
-				if (r.dispose) {
-					var result = r.dispose.call(r.value);
-					if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) {
-						fail(e);
-						return next();
-					});
-				} else s |= 1;
-			} catch (e) {
-				fail(e);
-			}
-			if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
-			if (env.hasError) throw env.error;
-		}
-		return next();
-	};
-})(typeof SuppressedError === "function" ? SuppressedError : function(error, suppressed, message) {
-	var e = new Error(message);
-	return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
-});
-/** Default maximum artifact size eligible for one cold projection observation. */
-const DEFAULT_COLD_BLANK_PROBE_MAX_BYTES = 1024;
-const COLD_SUMMARY_BATCH_SIZE = 16;
 const SEARCH_PROVIDER_CALL_LIMIT = 100;
 const SESSION_SEARCH_QUERY_MAX_CHARS = 500;
 const MESSAGE_TYPES = new Set(["user/message", "assistant/message"]);
@@ -1667,14 +1772,9 @@ function truncateUnicodeCodePoints(value, maximum) {
 /** Owns list projection registration, bounded cold summaries, and authorized search. */
 var ApiSessionList = class {
 	ctx;
-	coldBlankProbeMaxBytes;
-	/**
-	* @param ctx - Host context carrying Session, query, persistence, and projection services.
-	* @param coldBlankProbeMaxBytes - maximum physical artifact size eligible for a full observation.
-	*/
-	constructor(ctx, coldBlankProbeMaxBytes) {
+	/** @param ctx - Host context carrying Session, query, persistence, and projection services. */
+	constructor(ctx) {
 		this.ctx = ctx;
-		this.coldBlankProbeMaxBytes = coldBlankProbeMaxBytes;
 		ctx.sessionProjections.register({
 			key: "sessionListMetadata",
 			stateSchema: sessionListMetadataSchema,
@@ -1740,21 +1840,12 @@ var ApiSessionList = class {
 			if (record.header.cwd === void 0) continue;
 			cold.push(record.header);
 		}
-		for (let offset = 0; offset < cold.length; offset += COLD_SUMMARY_BATCH_SIZE) {
-			const settled = await Promise.allSettled(cold.slice(offset, offset + COLD_SUMMARY_BATCH_SIZE).map((header) => this.summarizeCold(header, signal)));
-			for (const result of settled) {
-				if (result.status === "rejected") throw result.reason;
-				items.push(result.value);
-			}
-		}
+		for (const header of cold) items.push(this.summarizeCold(header));
 		items.sort((left, right) => right.updatedAt - left.updatedAt);
 		return items;
 	}
-	async summarizeCold(header, signal) {
-		const cached = this.projectionsFor(header, void 0);
-		const projections = cached?.values.sessionListMetadata?.blank === false ? cached : await this.probeSmallCold(header, signal) ?? cached;
-		const raced = this.ctx.sessions.get(header.id);
-		if (raced !== void 0) return this.summaryFor(raced);
+	summarizeCold(header) {
+		const projections = this.projectionsFor(header, void 0);
 		const metadata = projections?.values.sessionListMetadata;
 		return {
 			sessionId: header.id,
@@ -1765,44 +1856,6 @@ var ApiSessionList = class {
 			...projections === void 0 ? {} : { projections }
 		};
 	}
-	async probeSmallCold(header, signal) {
-		if (this.coldBlankProbeMaxBytes === 0) return void 0;
-		const location = this.ctx.get("sessionPersistence")?.locate(header);
-		if (location === void 0) return void 0;
-		signal?.throwIfAborted();
-		try {
-			if ((await stat(location.path)).size > this.coldBlankProbeMaxBytes) return void 0;
-		} catch {
-			signal?.throwIfAborted();
-			return;
-		}
-		try {
-			const env_1 = {
-				stack: [],
-				error: void 0,
-				hasError: false
-			};
-			try {
-				const block = __addDisposableResource$2(env_1, await this.ctx.sessionQuery.observeSession(header.id, {
-					...signal === void 0 ? {} : { signal },
-					projectionMode: "all"
-				}), false).projections;
-				return block === void 0 ? void 0 : {
-					asOfSeq: block.asOfSeq,
-					values: block.values
-				};
-			} catch (e_1) {
-				env_1.error = e_1;
-				env_1.hasError = true;
-			} finally {
-				__disposeResources$2(env_1);
-			}
-		} catch (error) {
-			signal?.throwIfAborted();
-			this.ctx.logger.warn(`api-session.list: small cold observation for "${header.id}" failed; serving it as visible: ${String(error)}`);
-			return;
-		}
-	}
 	/**
 	* Search current visible message content without activating any matching Session.
 	* @param query - literal message-content query.
@@ -1893,7 +1946,8 @@ var ApiSessionList = class {
 	}
 	projectionsFor(header, session) {
 		try {
-			const block = session === void 0 ? header.isSeeded ? void 0 : this.ctx.get("sessionProjectionCache")?.cachedSnapshot(header, SessionLogOffset(0)) : this.ctx.sessionProjections.cachedSnapshot(session);
+			const cache = this.ctx.get("sessionProjectionCache");
+			const block = session === void 0 ? header.isSeeded ? void 0 : cache?.cachedSnapshot(header, SessionLogOffset(0)) ?? cache?.cachedPredecessorTitle(header, SessionLogOffset(0)) : this.ctx.sessionProjections.cachedSnapshot(session);
 			return block !== void 0 && Object.keys(block.values).length > 0 ? {
 				asOfSeq: block.asOfSeq,
 				values: block.values
@@ -2247,6 +2301,79 @@ let SessionSkillCatalog = (() => {
 	};
 })();
 //#endregion
+//#region lib/types/media-references.js
+/**
+* Authenticated GET/HEAD /api/file reads bounded file responses through
+* the composed filesystem provider. Paths and MIME types do not restrict access;
+* the connection service authenticates requests before this handler.
+* @module @deepseek-ai/dsh-api-session-controller/media-references
+*/
+const BASE_HEADERS = {
+	"Cache-Control": "private, no-store",
+	"X-Content-Type-Options": "nosniff",
+	"Content-Security-Policy": "sandbox; default-src 'none'"
+};
+async function serveFile(request, fs, maxBytes) {
+	const fail = (status, text) => new Response(request.method === "HEAD" ? null : text, {
+		status,
+		headers: BASE_HEADERS
+	});
+	const path = new URL(request.url).searchParams.get("path");
+	if (path === null || path.length === 0) return fail(400, "missing path");
+	if (path.includes("\0") || !isAbsolute(path)) return fail(400, "absolute path required");
+	try {
+		const target = await fs.resolve(path, { signal: request.signal });
+		const mediaType = mime.lookup(target.displayPath) || "application/octet-stream";
+		const headers = {
+			...BASE_HEADERS,
+			"Content-Type": mediaType
+		};
+		if (request.method === "HEAD") {
+			const info = await fs.stat(target, request.signal);
+			if (info === void 0) return fail(404, "not found");
+			if (info.type !== "file") return fail(403, "not a regular file");
+			if (info.size !== void 0) {
+				if (info.size > maxBytes) return fail(413, "file exceeds byte limit");
+				headers["Content-Length"] = String(info.size);
+			}
+			return new Response(null, { headers });
+		}
+		const bytes = await fs.readBytes(target, request.signal, maxBytes);
+		headers["Content-Length"] = String(bytes.byteLength);
+		return new Response(bytes.slice(), { headers });
+	} catch (error) {
+		if (!(error instanceof FsError)) throw error;
+		return fail({
+			FS_NOT_FOUND: 404,
+			FS_NOT_REGULAR_FILE: 403,
+			FS_PERMISSION_DENIED: 403,
+			FS_SANDBOX_DENIED: 403,
+			FS_TOO_LARGE: 413,
+			FS_ABORTED: 499
+		}[error.code] ?? 500, error.code);
+	}
+}
+/**
+* File-display contribution. The connection service supplies authentication;
+* `ctx.fs` supplies the execution world's paths, reads, and access policy.
+*/
+const SessionMediaReferences = {
+	inject: [
+		"connection",
+		"fs",
+		"attachments"
+	],
+	apply(ctx) {
+		const maxBytes = ctx.attachments.imageLimits.maxImageBytes;
+		ctx.effect(() => ctx.connection.fetch.register({
+			path: "/api/file",
+			methods: ["GET", "HEAD"],
+			requestBody: "buffered",
+			fetch: (request) => serveFile(request, ctx.fs, maxBytes)
+		}), "session-controller: /api/file");
+	}
+};
+//#endregion
 //#region lib/types/index.js
 /** Session Remote owner: cold reads, explicit Agent commands, and live control state. */
 var __runInitializers = function(thisArg, initializers, value) {
@@ -2571,6 +2698,7 @@ let SessionController = (() => {
 			"agentDefaultModel",
 			"agents",
 			"attachments",
+			"fileUploads",
 			"llm",
 			"sessions",
 			"sessionProjections",
@@ -2578,10 +2706,7 @@ let SessionController = (() => {
 			"typert",
 			"workspaceRegistry"
 		];
-		static Config = z.object({
-			coldBlankProbeMaxBytes: z.natural().default(DEFAULT_COLD_BLANK_PROBE_MAX_BYTES),
-			nativeOpen: z.boolean()
-		});
+		static Config = z.object({ nativeOpen: z.boolean() });
 		agents = __runInitializers(this, _instanceExtraInitializers);
 		commands;
 		controlState;
@@ -2592,13 +2717,19 @@ let SessionController = (() => {
 		promotions = /* @__PURE__ */ new Set();
 		/**
 		* @param ctx - Host context containing the Session capability assembly.
-		* @param config - cold-list observation policy.
+		* @param config - native-opener deployment policy.
+		* @param internals - host integrations replaceable by direct unit tests.
 		*/
 		constructor(ctx, config, internals = {}) {
 			super(ctx, "sessionController", { namespace: "session" });
 			installModelSelectionProjection(ctx);
 			this.agents = new ApiSessionAgentController(ctx);
 			this.commands = new SessionCommandController(ctx, this.agents, process.cwd());
+			ctx.effect(() => ctx.fileUploads.registerAgentResolver(async (sessionId) => {
+				const result = await this.agents.resolveAgent(sessionId);
+				if ("error" in result) throw result.error;
+				return result.agent;
+			}), "session-controller: file-upload Agent resolver");
 			this.controlState = new SessionControlController(ctx);
 			ctx.effect(() => async () => {
 				await Promise.allSettled([...this.promotions]);
@@ -2606,10 +2737,11 @@ let SessionController = (() => {
 			this.history = new SessionHistoryController(ctx, (observation) => {
 				this.promote(observation);
 			});
-			this.listState = new ApiSessionList(ctx, config.coldBlankProbeMaxBytes ?? 1024);
+			this.listState = new ApiSessionList(ctx);
 			this.openPath = internals.openPath ?? openNativePath;
 			this.canOpenPath = internals.canOpenPath ?? (() => config.nativeOpen ?? (internals.openPath !== void 0 || canOpenNativePath()));
 			ctx.plugin(SessionFileReferences);
+			ctx.plugin(SessionMediaReferences);
 			ctx.plugin(SessionSkillCatalog);
 			ctx.on("session/created", (session) => {
 				ctx.emit("api-session/added", this.listState.summaryFor(session));
@@ -2810,7 +2942,8 @@ let SessionController = (() => {
 		* Follow one Session log from its opening or resume cursor.
 		* @param request - durable address and last committed sequence already held by the caller.
 		* @param signal - cancellation owned by the Remote stream carrier.
-		* @returns a complete opening snapshot followed by gap-free event frames.
+		* @returns a complete opening snapshot followed by gap-free durable event
+		*   frames and optional cursorless assistant-stream frames.
 		*/
 		follow(request, signal) {
 			return this.history.follow(request, signal);