@deepseek-ai/dsh-api-session-controller 0.1.6-alpha.1 → 0.1.7-alpha.1

package/lib/index.js

@@ -1,14 +1,16 @@
 import { hostname } from "node:os";
+import { isAbsolute, resolve } from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { AssistantStreamAccumulator, ReasoningEffortId, assistantStreamChunks, createUserMessage, errorChain, freezeMessage } from "@deepseek-ai/dsh-llm";
-import { canOpenNativePath, nativeFileManager, openNativePath, revealNativePath } from "@deepseek-ai/dsh-native-command";
+import { canOpenNativePath, nativeFileApplications, nativeFileManager, openNativeAssociatedPath, openNativeFileApplication, revealNativePath } from "@deepseek-ai/dsh-native-command";
+import { SessionQueryError } from "@deepseek-ai/dsh-session-query";
 import { Remote, RemoteError, TypertRemoteService, remoteErrorOf } from "@deepseek-ai/dsh-typert-protocol";
 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 } from "@deepseek-ai/dsh-attachment";
+import { buildForkSeed } from "@deepseek-ai/dsh-session/fork";
 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";
@@ -16,7 +18,6 @@ import { assertNever } from "@deepseek-ai/dsh-util-values";
 import { Deque } from "@deepseek-ai/dsh-deque";
 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
@@ -227,7 +228,8 @@ var ApiSessionAgentController = class {
 			this.resumes.set(sessionId, resume);
 		}
 		try {
-			return { agent: await resume };
+			const agent = await resume;
+			return this.liveAgent(sessionId) ?? { agent };
 		} catch (error) {
 			if (error instanceof ApiSessionNotFound) return { error: new RemoteError("session/not-found", error.message, { sessionId }) };
 			if (error instanceof ApiSessionSubagentOwnership) return { error: apiSessionSubagentOwnershipError(error.sessionId) };
@@ -235,6 +237,7 @@ var ApiSessionAgentController = class {
 			if (raced !== void 0) return raced;
 			const racedSession = this.ctx.sessions.get(sessionId);
 			if (racedSession !== void 0 && hasApiSessionSubagentOwner(this.ctx, racedSession, void 0)) return { error: apiSessionSubagentOwnershipError(sessionId) };
+			if (error instanceof Error && error.name === "SessionAlreadyOwnedError") return { error: new RemoteError("session/writer-held", error.message, { sessionId }) };
 			return { error: new RemoteError("gateway/internal", `resume failed for session "${sessionId}": ${String(error)}`, {}) };
 		}
 	}
@@ -548,6 +551,20 @@ var __disposeResources$3 = (function(SuppressedError) {
 function hasPromptContent(content) {
 	return content.some((part) => part.type !== "text" || part.text.trim().length > 0);
 }
+/**
+* Resolve the omitted-`atSeq` default to the latest completed-turn prefix,
+* including standalone events before the next turn begins.
+*/
+function latestCompletedPrefixBoundary(events) {
+	const lastTurnEnd = events.findLast((event) => event.type === "turn/end");
+	if (lastTurnEnd === void 0) return void 0;
+	let boundary = lastTurnEnd.seq;
+	for (const next of events.slice(boundary + 1)) {
+		if (next.type === "turn/start" || next.type === "user/message" && next.surfaceOp === "append" || next.type === "agent/inbox/spliced") break;
+		boundary = next.seq;
+	}
+	return boundary;
+}
 /** Implements Session business commands delegated by the Session Controller Remote service. */
 var SessionCommandController = class {
 	ctx;
@@ -653,8 +670,10 @@ var SessionCommandController = class {
 		}
 	}
 	/**
-	* Create a new ordinary Session from one completed-turn prefix.
-	* @param request - source Session and optional event anchor.
+	* Create a new ordinary Session from an exact event prefix. An explicit
+	* `atSeq` is the inclusive cut; an omitted value selects the latest
+	* completed-turn prefix. An open cut receives synthetic fork closers.
+	* @param request - source Session and optional exact event boundary.
 	* @returns the new Session identity.
 	*/
 	async fork(request) {
@@ -678,10 +697,9 @@ var SessionCommandController = class {
 				throw new RemoteError("gateway/internal", `fork source unavailable for session "${request.sessionId}": ${String(error)}`, {});
 			}
 			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 });
-			const cut = SessionLogOffset(boundary.seq + 1);
+			const boundary = atSeq ?? latestCompletedPrefixBoundary(source.events);
+			if (boundary === void 0 || source.events[boundary]?.seq !== boundary) throw new RemoteError("session/fork-unavailable", request.atSeq === void 0 ? `session "${request.sessionId}" has no completed turn to fork from` : `event ${String(request.atSeq)} does not exist in session "${request.sessionId}" (last seq: ${String(source.events.at(-1)?.seq ?? "none")})`, { sessionId: request.sessionId });
+			const seed = buildForkSeed(source.events, boundary);
 			let workspace;
 			try {
 				workspace = await this.forkWorkspace(source.header);
@@ -694,8 +712,8 @@ var SessionCommandController = class {
 				const { provider, model } = this.ctx.agentDefaultModel.currentSelection();
 				await this.ctx.agents.create({
 					sessionId: childId,
-					seed: source.events.slice(0, cut),
-					inheritedEventCount: cut,
+					seed,
+					inheritedEventCount: SessionLogOffset(boundary + 1),
 					meta: {
 						...source.header.cwd === void 0 ? {} : { cwd: source.header.cwd },
 						parentSession: source.header.id,
@@ -814,17 +832,24 @@ var SessionCommandController = class {
 		}
 	}
 	/**
-	* Mutate one still-pending queue occurrence without resuming a cold Agent.
+	* Mutate one pending Inbox occurrence, restoring an ordinary cold Agent when needed.
 	* @param request - Session, queue item, and requested mutation.
 	* @returns acknowledgement that the queue mutation was applied.
 	*/
-	updateQueue(request) {
+	async updateQueue(request) {
 		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) throw new RemoteError("session/queue-item-not-found", "queued item is no longer pending", { itemId: request.itemId });
+		let agent = this.ctx.agents.get(request.sessionId);
+		if (agent === void 0) {
+			const found = await this.agents.resolveAgent(request.sessionId);
+			if ("error" in found) {
+				if (found.error.code !== "session/not-found") throw found.error;
+				throw new RemoteError("session/queue-item-not-found", "queued item is no longer pending", { itemId: request.itemId });
+			}
+			agent = found.agent;
+		}
 		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);
@@ -882,6 +907,7 @@ var SessionCommandController = class {
 	}
 	rejectCreation(sessionId, error) {
 		if (remoteErrorOf(error) !== void 0) throw error;
+		if (error instanceof Error && error.name === "SessionAlreadyOwnedError") throw new RemoteError("session/writer-held", error.message, { sessionId });
 		if (error instanceof ApiSessionPresetConflict) throw new RemoteError("agent-preset/conflict", error.message, {
 			sessionId: error.sessionId,
 			requestedPreset: error.requestedPreset,
@@ -957,23 +983,39 @@ function imageBlockIn(content, match) {
 			const ref = block.attachment;
 			if (match(ref)) return ref;
 		}
-		if (block.type === "tool-result") {
-			const nested = imageBlockIn(block.content, match);
-			if (nested !== void 0) return nested;
-		}
 	}
 }
+/** Read only first-party declared content fields; unknown event payloads stay opaque. */
 function imageInEvent(event, match) {
 	const data = event.data;
-	const direct = imageBlockIn(data.content, match);
-	if (direct !== void 0) return direct;
-	const message = imageBlockIn(data.message?.content, match);
-	if (message !== void 0) return message;
-	for (const inserted of data.inserted ?? []) {
-		const found = imageBlockIn(inserted.content, match);
-		if (found !== void 0) return found;
+	switch (event.type) {
+		case "user/message":
+		case "tool/ptc-dispatch": return imageBlockIn(data.content, match);
+		case "system/message":
+		case "developer/message":
+		case "tool/result":
+		case "team/message/queued": return imageBlockIn(data.message?.content, match);
+		case "agent/inbox/spliced": {
+			const messages = data.inserted;
+			if (!Array.isArray(messages)) return void 0;
+			for (const message of messages) {
+				if (typeof message !== "object" || message === null || Array.isArray(message)) continue;
+				const found = imageBlockIn(message.content, match);
+				if (found !== void 0) return found;
+			}
+			return;
+		}
+		case "compaction/summary": return imageBlockIn(data.summary, match) ?? imageBlockIn(data.rawOutput, match);
+		case "assistant/message": {
+			const found = imageBlockIn(data.message?.content, match);
+			if (found !== void 0) return found;
+			break;
+		}
+		case "assistant/attempt": break;
+		default: return;
 	}
-	if (event.type === "assistant/message" || event.type === "assistant/attempt") for (const chunk of assistantStreamChunks(event.data.stream, "block-end")) {
+	const assistant = event;
+	for (const chunk of assistantStreamChunks(assistant.data.stream, "block-end")) {
 		const found = imageBlockIn([chunk.block], match);
 		if (found !== void 0) return found;
 	}
@@ -989,12 +1031,12 @@ function routeServed(ctx, provider) {
 }
 //#endregion
 //#region lib/types/control.js
-/** Live Session queue, jobs, and projection state with reconnect baselines. */
+/** Live Session projection state with reconnect baselines. */
 /** Owns the Host-wide Session control stream. */
 var SessionControlController = class {
 	ctx;
 	streams = /* @__PURE__ */ new Set();
-	/** @param ctx - Host context carrying live Agent, projection, and jobs services. */
+	/** @param ctx - Host context carrying live Agent and projection services. */
 	constructor(ctx) {
 		this.ctx = ctx;
 		ctx.sessionProjections.onChanged((session, key, value, seq) => {
@@ -1005,26 +1047,6 @@ 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) => {
-				this.onJobsChanged(owner);
-			});
-		});
-		ctx.on("session/created", (session) => {
-			const jobs = this.jobsFor(this.ctx.agents.get(session.id));
-			if (jobs.length > 0) this.broadcast({
-				type: "jobs",
-				sessionId: session.id,
-				jobs
-			});
 		});
 		ctx.effect(() => () => {
 			for (const stream of this.streams) stream.end();
@@ -1053,18 +1075,7 @@ var SessionControlController = class {
 	}
 	baseline() {
 		const sessions = this.ctx.sessions.list();
-		const queues = Object.create(null);
-		const jobs = Object.create(null);
-		for (const session of sessions) {
-			const agent = this.ctx.agents.get(session.id);
-			queues[session.id] = agent?.session === session ? queueItems(agent) : [];
-			jobs[session.id] = this.jobsFor(agent);
-		}
-		return {
-			queues,
-			jobs,
-			projections: this.projectionBaseline(sessions)
-		};
+		return { projections: this.projectionBaseline(sessions) };
 	}
 	projectionBaseline(sessions) {
 		const blocks = Object.create(null);
@@ -1077,25 +1088,6 @@ var SessionControlController = class {
 		}
 		return blocks;
 	}
-	onJobsChanged(owner) {
-		if (owner !== void 0) {
-			this.broadcast({
-				type: "jobs",
-				sessionId: owner.id,
-				jobs: this.jobsFor(owner)
-			});
-			return;
-		}
-		for (const session of this.ctx.sessions.list()) this.broadcast({
-			type: "jobs",
-			sessionId: session.id,
-			jobs: this.jobsFor(this.ctx.agents.get(session.id))
-		});
-	}
-	jobsFor(agent) {
-		const jobs = this.ctx.get("jobs");
-		return jobs === void 0 ? [] : jobs.list(agent).map(jobView);
-	}
 	broadcast(frame) {
 		for (const stream of this.streams) stream.push(frame);
 	}
@@ -1141,47 +1133,6 @@ var ControlQueue = class {
 		}
 	}
 };
-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),
-		message: {
-			id: message.id,
-			content: message.content
-		}
-	})), ...inbox["next-step"].map((message) => ({
-		id: message.id,
-		placement: message.source.kind === "user" ? "steering" : "context",
-		...promptRpcId(message),
-		message: {
-			id: message.id,
-			content: message.content
-		}
-	}))];
-}
-/** Prompt-RPC identity carried by a browser-submitted message's user source. */
-function promptRpcId(message) {
-	const source = message.source;
-	return source.kind === "user" && "rpcId" in source ? { rpcId: source.rpcId } : {};
-}
-function jobView(job) {
-	return {
-		id: job.id,
-		kind: job.kind,
-		label: job.label,
-		status: job.status,
-		...job.detail === void 0 ? {} : { detail: job.detail },
-		startedAt: job.startedAt,
-		...job.finishedAt === void 0 ? {} : { finishedAt: job.finishedAt }
-	};
-}
 //#endregion
 //#region lib/types/assistant-stream.js
 /** Process-local assistant state retained for reconnecting Web followers. */
@@ -1589,7 +1540,7 @@ function validateAddress(address, header, inheritedEventCount, projections) {
 		childSessionId: address.childSessionId,
 		reason: "unsupported"
 	});
-	if (identity.mode !== address.mode) throw new RemoteError("subagent/unauthorized", "subagent mode does not match the supplied address", { childSessionId: address.childSessionId });
+	if (address.mode !== "unknown" && identity.mode !== address.mode) throw new RemoteError("subagent/unauthorized", "subagent mode does not match the supplied address", { childSessionId: address.childSessionId });
 }
 function rejectNotFound(address) {
 	if (address.kind === "session") throw new RemoteError("session/not-found", `session "${address.sessionId}" not found`, { sessionId: address.sessionId });
@@ -1814,6 +1765,7 @@ var ApiSessionList = class {
 		return {
 			sessionId: session.id,
 			updatedAt: updatedAt(session.header, metadata),
+			agentAvailable: this.ctx.agents.get(session.id)?.session === session,
 			running: this.ctx.agents.get(session.id)?.status === "running",
 			blank: metadata?.blank ?? session.seq === 0,
 			...listFields(session.header),
@@ -1850,6 +1802,7 @@ var ApiSessionList = class {
 		return {
 			sessionId: header.id,
 			updatedAt: updatedAt(header, metadata),
+			agentAvailable: false,
 			running: false,
 			blank: metadata?.blank ?? false,
 			...listFields(header),
@@ -1946,18 +1899,29 @@ var ApiSessionList = class {
 	}
 	projectionsFor(header, session) {
 		try {
+			if (session !== void 0) return hintsOf("sequenced", 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
-			} : void 0;
+			return hintsOf("cached", cache?.cachedSnapshot(header) ?? cache?.cachedPredecessorTitle(header));
 		} catch (error) {
 			this.ctx.logger.warn(`api-session.list: projection column for "${header.id}" failed; serving the row without it: ${String(error)}`);
 			return;
 		}
 	}
 };
+/**
+* Wrap one projection block as Session-list hints of the named sequence space.
+* @param kind - which sequence space the block's watermark belongs to.
+* @param block - the block, or `undefined` when no source served one.
+* @returns the hints, or `undefined` when the block is absent or carries no value.
+*/
+function hintsOf(kind, block) {
+	if (block === void 0 || Object.keys(block.values).length === 0) return void 0;
+	return {
+		kind,
+		asOfSeq: block.asOfSeq,
+		values: block.values
+	};
+}
 function normalizeSearchQuery(query) {
 	const normalized = query.trim();
 	if (normalized.length === 0) throw new RemoteError("gateway/bad-request", "session search query must not be empty", {});
@@ -2242,59 +2206,71 @@ let SessionSkillCatalog = (() => {
 		* @throws RemoteError when the Session cannot be inspected or no registry can serve it.
 		*/
 		async list(request, signal) {
-			const { sessionId } = request;
-			let cwd;
-			let agentPreset;
+			const env_1 = {
+				stack: [],
+				error: void 0,
+				hasError: false
+			};
 			try {
-				const env_1 = {
-					stack: [],
-					error: void 0,
-					hasError: false
-				};
+				const { sessionId } = request;
+				let cwd;
+				let agentPreset;
 				try {
-					const observation = __addDisposableResource$1(env_1, await this.ctx.sessionQuery.observeSession(sessionId), false);
-					if (observation.projections === void 0) throw new Error("skill catalog requires a projected Session observation");
-					cwd = observation.header.cwd;
-					agentPreset = observation.projections.values.agentPreset ?? void 0;
-				} catch (e_1) {
-					env_1.error = e_1;
-					env_1.hasError = true;
-				} finally {
-					__disposeResources$1(env_1);
+					const env_2 = {
+						stack: [],
+						error: void 0,
+						hasError: false
+					};
+					try {
+						const observation = __addDisposableResource$1(env_2, await this.ctx.sessionQuery.observeSession(sessionId), false);
+						if (observation.projections === void 0) throw new Error("skill catalog requires a projected Session observation");
+						cwd = observation.header.cwd;
+						agentPreset = observation.projections.values.agentPreset ?? void 0;
+					} catch (e_1) {
+						env_2.error = e_1;
+						env_2.hasError = true;
+					} finally {
+						__disposeResources$1(env_2);
+					}
+				} catch (error) {
+					if (error instanceof SessionQueryError && error.code === "SESSION_QUERY_SESSION_NOT_FOUND") throw new RemoteError("session/not-found", `session "${sessionId}" not found`, { sessionId });
+					throw new RemoteError("gateway/internal", `session "${sessionId}" could not be inspected: ${String(error)}`, {});
 				}
-			} catch (error) {
-				if (error instanceof SessionQueryError && error.code === "SESSION_QUERY_SESSION_NOT_FOUND") throw new RemoteError("session/not-found", `session "${sessionId}" not found`, { sessionId });
-				throw new RemoteError("gateway/internal", `session "${sessionId}" could not be inspected: ${String(error)}`, {});
-			}
-			if (cwd === void 0) throw new RemoteError("gateway/internal", `session "${sessionId}" has no project cwd`, {});
-			const live = this.ctx.agents.get(sessionId);
-			const presets = this.ctx.get("agentPresets");
-			const skillRegistry = (live === void 0 ? void 0 : presets?.serviceFor(live, "skills")) ?? this.ctx.get("skills");
-			if (skillRegistry === void 0) throw new RemoteError("gateway/internal", "skill registry is absent: neither this session's agent preset nor the host composition mounts @deepseek-ai/dsh-skill", {});
-			const scope = await this.scopeFor(sessionId, agentPreset);
-			try {
-				return { skills: (await skillRegistry.list({
-					cwd,
-					scope
-				})).filter(isUserInvocable).map((skill) => ({
-					name: skill.name,
-					...skill.path === void 0 ? {} : { path: skill.path },
-					description: skill.description,
-					...skill.whenToUse === void 0 ? {} : { whenToUse: skill.whenToUse },
-					modelInvocable: skill.invocation.modelInvocable
-				})) };
-			} catch (error) {
-				throw new RemoteError("gateway/internal", `skill listing failed: ${String(error)}`, {});
+				if (cwd === void 0) throw new RemoteError("gateway/internal", `session "${sessionId}" has no project cwd`, {});
+				const live = this.ctx.agents.get(sessionId);
+				const presets = this.ctx.get("agentPresets");
+				const skillRegistry = (live === void 0 ? void 0 : presets?.serviceFor(live, "skills")) ?? this.ctx.get("skills");
+				if (skillRegistry === void 0) throw new RemoteError("gateway/internal", "skill registry is absent: neither this session's agent preset nor the host composition mounts @deepseek-ai/dsh-skill", {});
+				const lease = __addDisposableResource$1(env_1, live === void 0 ? await this.scopeFor(agentPreset) : void 0, true);
+				const scope = live ?? lease?.key;
+				try {
+					return { skills: (await skillRegistry.list({
+						cwd,
+						scope
+					})).filter(isUserInvocable).map((skill) => ({
+						name: skill.name,
+						...skill.path === void 0 ? {} : { path: skill.path },
+						description: skill.description,
+						...skill.whenToUse === void 0 ? {} : { whenToUse: skill.whenToUse },
+						modelInvocable: skill.invocation.modelInvocable
+					})) };
+				} catch (error) {
+					throw new RemoteError("gateway/internal", `skill listing failed: ${String(error)}`, {});
+				}
+			} catch (e_2) {
+				env_1.error = e_2;
+				env_1.hasError = true;
+			} finally {
+				const result_1 = __disposeResources$1(env_1);
+				if (result_1) await result_1;
 			}
 		}
 		/** Resolve a live or standing preset scope without creating an Agent. */
-		async scopeFor(sessionId, agentPreset) {
-			const live = this.ctx.agents.get(sessionId);
-			if (live !== void 0) return live;
+		async scopeFor(agentPreset) {
 			const presets = this.ctx.get("agentPresets");
 			if (presets === void 0) return void 0;
 			try {
-				return await presets.standingKeyFor(agentPreset);
+				return await presets.acquireScope(agentPreset);
 			} catch {
 				return;
 			}
@@ -2375,6 +2351,58 @@ const SessionMediaReferences = {
 	}
 };
 //#endregion
+//#region lib/types/archived-session-gate.js
+/**
+* The controller's admission gate for archived Sessions: an archived
+* Session, or a subagent descendant of one, must not run a model step until
+* it is restored. The work a Session still runs is reported and stopped by
+* its owners — the Agent registry (`turn`), the job registry seam (`job`),
+* the Subagent runtime (`subagent`), and the Schedule plugin (`schedule`) —
+* through the Workspace registry's archive-admission events.
+*/
+/**
+* The gate as a plugin for `ctx.plugin(...)`: it loads once the Agent
+* registry, Session store, and Workspace registry are available and unwinds
+* with the plugin's fiber. A late waking delivery to an archived Session — a
+* subagent settlement, a queued follow-up — proposes a step the gate rejects,
+* which the loop ends as `blocked` without a request; unarchiving lifts the
+* gate for the whole lineage.
+*/
+const ArchivedSessionGate = {
+	name: "archived-session-gate",
+	inject: [
+		"agents",
+		"sessions",
+		"workspaceRegistry"
+	],
+	apply(ctx) {
+		ctx.on("agent/pre-step", (payload, next) => underArchivedSession(ctx, payload.agent) ? Promise.resolve({ kind: "reject" }) : next());
+	}
+};
+/**
+* Whether the Agent's Session, or a Session above it in its subagent lineage,
+* is archived. Lineage follows the durable header fields through
+* subagent-origin Sessions only: a fork of an archived Session is an
+* independent conversation.
+* @param ctx - Host context.
+* @param agent - the Agent proposing a step.
+* @returns whether an archived Session owns the step.
+*/
+function underArchivedSession(ctx, agent) {
+	const archived = ctx.workspaceRegistry.archivedSessionIds;
+	let header = agent.session.header;
+	const visited = /* @__PURE__ */ new Set();
+	while (!visited.has(header.id)) {
+		if (archived.includes(header.id)) return true;
+		visited.add(header.id);
+		if (header.origin !== "subagent" || header.parentSession === void 0) return false;
+		const parent = ctx.sessions.get(header.parentSession);
+		if (parent === void 0) return archived.includes(header.parentSession);
+		header = parent.header;
+	}
+	return false;
+}
+//#endregion
 //#region lib/types/index.js
 /** Session Remote owner: cold reads, explicit Agent commands, and live control state. */
 var __runInitializers = function(thisArg, initializers, value) {
@@ -2484,6 +2512,7 @@ let SessionController = (() => {
 	let _modelCatalog_decorators;
 	let _canOpenWorkspacePath_decorators;
 	let _openWorkspacePath_decorators;
+	let _workspacePathApplications_decorators;
 	let _rename_decorators;
 	let _fork_decorators;
 	let _prompt_decorators;
@@ -2492,6 +2521,7 @@ let SessionController = (() => {
 	let _cancel_decorators;
 	let _page_decorators;
 	let _follow_decorators;
+	let _projections_decorators;
 	let _control_decorators;
 	return class SessionController extends _classSuper {
 		static {
@@ -2503,6 +2533,7 @@ let SessionController = (() => {
 			_modelCatalog_decorators = [Remote("modelCatalog")];
 			_canOpenWorkspacePath_decorators = [Remote];
 			_openWorkspacePath_decorators = [Remote("openWorkspacePath")];
+			_workspacePathApplications_decorators = [Remote("workspacePathApplications")];
 			_rename_decorators = [Remote("rename")];
 			_fork_decorators = [Remote("fork")];
 			_prompt_decorators = [Remote("prompt")];
@@ -2511,6 +2542,7 @@ let SessionController = (() => {
 			_cancel_decorators = [Remote("cancel")];
 			_page_decorators = [Remote("page")];
 			_follow_decorators = [Remote({ mode: "stream" })];
+			_projections_decorators = [Remote("projections")];
 			_control_decorators = [Remote({ mode: "stream" })];
 			__esDecorate(this, null, _list_decorators, {
 				kind: "method",
@@ -2589,6 +2621,17 @@ let SessionController = (() => {
 				},
 				metadata: _metadata
 			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _workspacePathApplications_decorators, {
+				kind: "method",
+				name: "workspacePathApplications",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "workspacePathApplications" in obj,
+					get: (obj) => obj.workspacePathApplications
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
 			__esDecorate(this, null, _rename_decorators, {
 				kind: "method",
 				name: "rename",
@@ -2677,6 +2720,17 @@ let SessionController = (() => {
 				},
 				metadata: _metadata
 			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _projections_decorators, {
+				kind: "method",
+				name: "projections",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "projections" in obj,
+					get: (obj) => obj.projections
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
 			__esDecorate(this, null, _control_decorators, {
 				kind: "method",
 				name: "control",
@@ -2700,6 +2754,7 @@ let SessionController = (() => {
 			"agents",
 			"attachments",
 			"fileUploads",
+			"fs",
 			"llm",
 			"sessions",
 			"sessionProjections",
@@ -2714,6 +2769,8 @@ let SessionController = (() => {
 		history;
 		listState;
 		openPath;
+		fileApplications;
+		openFileApplication;
 		revealPath;
 		canOpenPath;
 		promotions = /* @__PURE__ */ new Set();
@@ -2740,18 +2797,26 @@ let SessionController = (() => {
 				this.promote(observation);
 			});
 			this.listState = new ApiSessionList(ctx);
-			this.openPath = internals.openPath ?? openNativePath;
+			this.fileApplications = internals.fileApplications ?? nativeFileApplications;
+			this.openFileApplication = internals.openFileApplication ?? openNativeFileApplication;
+			this.openPath = internals.openPath ?? openNativeAssociatedPath;
 			this.revealPath = internals.revealPath ?? revealNativePath;
 			this.canOpenPath = internals.canOpenPath ?? (() => config.nativeOpen ?? (internals.openPath !== void 0 || canOpenNativePath()));
 			ctx.plugin(SessionFileReferences);
 			ctx.plugin(SessionMediaReferences);
 			ctx.plugin(SessionSkillCatalog);
+			ctx.plugin(ArchivedSessionGate);
 			ctx.on("session/created", (session) => {
 				ctx.emit("api-session/added", this.listState.summaryFor(session));
 			});
 			ctx.on("session/disposed", (session) => {
 				ctx.emit("api-session/removed", session.id);
 			});
+			const publishAgentAvailability = ({ agent }) => {
+				if (ctx.sessions.get(agent.id) === agent.session) ctx.emit("api-session/added", this.listState.summaryFor(agent.session));
+			};
+			ctx.on("agent/created", publishAgentAvailability);
+			ctx.on("agent/disposed", publishAgentAvailability);
 			ctx.on("agent/status", ({ agent, status }) => {
 				ctx.emit("api-session/status", agent.id, status === "running");
 			});
@@ -2877,24 +2942,53 @@ let SessionController = (() => {
 			};
 		}
 		/**
-		* Open one path prepared by a Session-aware caller on the Host desktop.
+		* Verify one path through the composed filesystem and open it on the Host desktop.
 		* @param request - path after best-effort Session workspace resolution.
 		* @param signal - caller lifetime; abort terminates the native command.
 		* @returns confirmation after the native opener accepts the path.
-		* @throws RemoteError when the request is invalid, cancelled, or the opener fails.
+		* @throws RemoteError when the request is invalid, has no verified Host mapping, is cancelled, or the opener fails.
 		*/
 		async openWorkspacePath(request, signal) {
-			if (request.path.length === 0) throw new RemoteError("gateway/bad-request", "session.openWorkspacePath requires a non-empty path", {});
-			signal.throwIfAborted();
 			try {
-				if (request.action === "reveal") await this.revealPath(request.path, signal);
-				else await this.openPath(request.path, signal);
+				const path = await this.verifyDesktopPath(request.path, signal);
+				if (request.action === "reveal") await this.revealPath(path, signal);
+				else if (request.application !== void 0) await this.openFileApplication(path, request.application, signal);
+				else await this.openPath(path, signal);
 				return { opened: true };
 			} catch (error) {
 				if (signal.aborted) throw new RemoteError("gateway/cancelled", "path open was aborted", {});
-				throw new RemoteError("gateway/internal", `path open failed: ${error instanceof Error ? error.message : String(error)}`, {});
+				if (error instanceof RemoteError) throw error;
+				throw new RemoteError("gateway/internal", "path open failed", {}, { cause: error });
+			}
+		}
+		/**
+		* Query current file handlers on the serving desktop without activating an Agent.
+		* @param request - file path in Host filesystem syntax.
+		* @param signal - caller lifetime, propagated to filesystem and desktop queries.
+		* @returns OS application names, icons, and default selection; empty when desktop opening is unavailable.
+		* @throws RemoteError when the path is invalid, the query is cancelled, or native discovery fails.
+		*/
+		async workspacePathApplications(request, signal) {
+			if (!this.canOpenPath()) return [];
+			try {
+				const path = await this.verifyDesktopPath(request.path, signal);
+				return await this.fileApplications(path, signal);
+			} catch (error) {
+				if (signal.aborted) throw new RemoteError("gateway/cancelled", "application query was aborted", {});
+				if (error instanceof RemoteError) throw error;
+				throw new RemoteError("gateway/internal", "file application query failed", {}, { cause: error });
 			}
 		}
+		async verifyDesktopPath(path, signal) {
+			if (path.length === 0) throw new RemoteError("gateway/bad-request", "A non-empty file path is required", {});
+			signal.throwIfAborted();
+			const hostPath = resolve(path);
+			const { fs } = this.ctx;
+			const mapped = fs.processPathFromHostPath(hostPath);
+			if (mapped === void 0 || fs.processPath(await fs.resolve(mapped, { signal })) !== hostPath) throw new RemoteError("gateway/bad-request", "Path has no verified Host path", {});
+			signal.throwIfAborted();
+			return hostPath;
+		}
 		/**
 		* Rename one Session after explicitly resuming it.
 		* @param request - Session identity and proposed title.
@@ -2904,8 +2998,10 @@ let SessionController = (() => {
 			return this.commands.rename(request);
 		}
 		/**
-		* Fork one cold-readable completed-turn prefix into a new Session.
-		* @param request - source Session and optional event anchor.
+		* Fork one cold-readable exact event prefix into a new Session. An omitted
+		* boundary selects the latest completed-turn prefix; an open cut receives
+		* synthetic fork closers.
+		* @param request - source Session and optional exact inclusive event boundary.
 		* @returns the new Session identity.
 		*/
 		fork(request) {
@@ -2930,7 +3026,7 @@ let SessionController = (() => {
 			return this.commands.attachment(request);
 		}
 		/**
-		* Mutate one still-pending queue occurrence on a live Agent.
+		* Mutate one still-pending queue occurrence, resuming a cold Agent first.
 		* @param request - Session, queue item, and requested mutation.
 		* @returns acknowledgement that the queue mutation was applied.
 		*/
@@ -2965,6 +3061,41 @@ let SessionController = (() => {
 			return this.history.follow(request, signal);
 		}
 		/**
+		* Read all registered projections without activating an Agent.
+		* @param request - Session whose current values are required.
+		* @param signal - cancellation for the Session observation.
+		* @returns complete baseline, or null when the Session does not exist.
+		*/
+		async projections(request, signal) {
+			const { sessionId } = request;
+			if (sessionId.length === 0) throw new RemoteError("gateway/bad-request", "sessionId must not be empty", {});
+			try {
+				const env_2 = {
+					stack: [],
+					error: void 0,
+					hasError: false
+				};
+				try {
+					const projections = __addDisposableResource(env_2, await this.ctx.sessionQuery.observeSession(sessionId, { signal }), false).projections;
+					if (projections === void 0) throw new RemoteError("session/projections-unavailable", "Session projections are unavailable", {});
+					return {
+						asOfSeq: projections.asOfSeq,
+						values: projections.values
+					};
+				} catch (e_2) {
+					env_2.error = e_2;
+					env_2.hasError = true;
+				} finally {
+					__disposeResources(env_2);
+				}
+			} catch (error) {
+				if (error instanceof SessionQueryError && error.code === "SESSION_QUERY_SESSION_NOT_FOUND") return null;
+				if (signal.aborted || error instanceof SessionQueryError && error.code === "SESSION_QUERY_ABORTED") throw new RemoteError("gateway/cancelled", "Session projection read was cancelled", {}, { cause: error });
+				if (error instanceof RemoteError) throw error;
+				throw new RemoteError("gateway/internal", "Session projection read failed", {}, { cause: error });
+			}
+		}
+		/**
 		* Stream a complete live-control baseline followed by replacement frames.
 		* @param signal - cancellation owned by the Remote stream carrier.
 		* @returns one complete baseline followed by live replacement frames.