@deepseek-ai/dsh-api-terminal-controller 0.1.6-alpha.1 → 0.1.6-alpha.2

package/lib/index.js

@@ -1,7 +1,7 @@
-import { createRequire } from "node:module";
 import z from "@deepseek-ai/schemastery";
 import { Remote, RemoteError, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import { SubprocessExecutableNotFoundError } from "@deepseek-ai/dsh-subprocess";
+import { createLazyRequire } from "@deepseek-ai/dsh-lazy-require";
 import { Deque } from "@deepseek-ai/dsh-deque";
 //#region lib/types/shells.js
 /** Shell selection and executable verification use the target execution provider. */
@@ -139,18 +139,161 @@ var TerminalFollower = class {
 	}
 };
 //#endregion
+//#region lib/types/retention.js
+/** Window holds and conservative idle reclamation for one terminal owner. */
+/** Exactly one owner orders holds, observation, and retryable process cleanup. */
+var TerminalRetention = class {
+	policy;
+	inspect;
+	terminate;
+	failed;
+	lifetime = new AbortController();
+	holders = /* @__PURE__ */ new Set();
+	epoch = 0;
+	timer;
+	observation;
+	idle;
+	closing = false;
+	disposed = false;
+	cleanup;
+	/**
+	* @param policy - deployment timing choices.
+	* @param inspect - fresh shell and owned-job observation.
+	* @param terminate - mark the identity closed, await process quiescence, and remove its owner record.
+	* @param failed - diagnostic sink for failed automatic cleanup.
+	*/
+	constructor(policy, inspect, terminate, failed) {
+		this.policy = policy;
+		this.inspect = inspect;
+		this.terminate = terminate;
+		this.failed = failed;
+		this.schedule(0);
+	}
+	/**
+	* Hold one terminal for one physical Remote stream, independently of screen subscriptions.
+	* @param signal - transport generation lifetime.
+	* @returns acknowledgement followed by an open stream until cancellation or terminal closure.
+	*/
+	async *retain(signal) {
+		signal.throwIfAborted();
+		if (this.closing || this.disposed) throw new RemoteError("terminal/unavailable", "Terminal is closing or unavailable", {});
+		const holder = {};
+		const ended = Promise.withResolvers();
+		const combined = AbortSignal.any([signal, this.lifetime.signal]);
+		const release = () => {
+			if (!this.holders.delete(holder)) return;
+			combined.removeEventListener("abort", release);
+			this.invalidate();
+			ended.resolve();
+			this.schedule(0);
+		};
+		this.holders.add(holder);
+		this.invalidate();
+		this.cancelTimer();
+		combined.addEventListener("abort", release, { once: true });
+		try {
+			yield { type: "retained" };
+			await ended.promise;
+		} finally {
+			release();
+		}
+	}
+	/** Invalidate outstanding idle observations before accepting input. */
+	invalidate() {
+		this.epoch++;
+		this.idle = void 0;
+	}
+	/**
+	* Start or join cleanup; failure keeps the identity closed and schedules one retry.
+	* @returns after owned process cleanup succeeds, or rejects with its failure.
+	*/
+	close() {
+		if (this.cleanup !== void 0) return this.cleanup;
+		this.closing = true;
+		this.invalidate();
+		this.lifetime.abort(/* @__PURE__ */ new Error("Terminal closed"));
+		this.cancelTimer();
+		this.cleanup = this.terminate().catch((error) => {
+			this.cleanup = void 0;
+			this.schedule(this.policy.cleanupRetryMs);
+			throw error;
+		});
+		return this.cleanup;
+	}
+	/**
+	* Stop timers and streams and await both observation and final cleanup.
+	* @returns after process quiescence; cleanup failure is reported to the disposing owner.
+	*/
+	async dispose() {
+		this.disposed = true;
+		this.cancelTimer();
+		const observation = this.observation;
+		try {
+			await this.close();
+		} finally {
+			await observation;
+		}
+	}
+	cancelTimer() {
+		clearTimeout(this.timer);
+		this.timer = void 0;
+	}
+	schedule(delay) {
+		if (this.disposed || this.timer !== void 0) return;
+		if (!this.closing && (this.holders.size > 0 || this.policy.unattendedTimeoutMs === 0)) return;
+		const due = performance.now() + delay;
+		this.timer = setTimeout(() => {
+			this.timer = void 0;
+			const remaining = due - performance.now();
+			if (remaining > 0) {
+				this.schedule(remaining);
+				return;
+			}
+			if (this.closing) {
+				this.close().catch(this.failed);
+				return;
+			}
+			this.observe();
+		}, Math.min(delay, 2147483647));
+		this.timer.unref();
+	}
+	observe() {
+		if (this.observation !== void 0) return;
+		const epoch = this.epoch;
+		this.observation = (async () => {
+			let activity;
+			try {
+				activity = await this.inspect();
+			} catch (_activityUnavailable) {
+				activity = {
+					state: "unknown",
+					revision: 0
+				};
+			}
+			if (this.disposed || this.closing || this.holders.size > 0 || epoch !== this.epoch) return;
+			const now = performance.now();
+			if (activity.state !== "idle") {
+				this.idle = void 0;
+				return;
+			}
+			if (this.idle?.revision !== activity.revision || now - this.idle.observedAt > this.policy.activityPollIntervalMs * 2) this.idle = {
+				since: now,
+				observedAt: now,
+				revision: activity.revision
+			};
+			else this.idle.observedAt = now;
+			if (now - this.idle.since >= this.policy.unattendedTimeoutMs) await this.close();
+		})().catch(this.failed).finally(() => {
+			this.observation = void 0;
+			if (!this.closing) this.schedule(this.policy.activityPollIntervalMs);
+		});
+	}
+};
+//#endregion
 //#region lib/types/terminal.js
 /** One PTY, a bounded terminal emulator and its detachable browser followers. */
-const { Terminal, SerializeAddon } = loadXterm();
-function loadXterm() {
-	const require = createRequire(import.meta.url);
-	const { Terminal } = require("@xterm/headless");
-	const { SerializeAddon } = require("@xterm/addon-serialize");
-	return {
-		Terminal,
-		SerializeAddon
-	};
-}
+const requireHeadless = createLazyRequire("@xterm/headless", import.meta.url);
+const requireSerialize = createLazyRequire("@xterm/addon-serialize", import.meta.url);
 /** Process lifetime is independent of follower and component lifetimes. */
 var BrowserTerminal = class {
 	handle;
@@ -163,6 +306,7 @@ var BrowserTerminal = class {
 	operations = Promise.resolve();
 	drained;
 	closing;
+	retention;
 	controller;
 	/**
 	* @param handle - allocated terminal process range.
@@ -174,6 +318,8 @@ var BrowserTerminal = class {
 		this.handle = handle;
 		this.info = info;
 		this.maxBufferedBytes = maxBufferedBytes;
+		const { Terminal } = requireHeadless();
+		const { SerializeAddon } = requireSerialize();
 		this.screen = new Terminal({
 			cols: info.cols,
 			rows: info.rows,
@@ -185,6 +331,29 @@ var BrowserTerminal = class {
 		this.drained = this.consume();
 	}
 	/**
+	* Start monitoring after this allocation is committed to its Session owner.
+	* @param policy - validated Host timing policy.
+	* @param closing - closes the id before any asynchronous termination.
+	* @param closed - removes the exact successfully terminated owner record.
+	* @param failed - diagnostic sink for background cleanup failure.
+	*/
+	monitor(policy, closing, closed, failed) {
+		this.retention = new TerminalRetention(policy, () => this.handle.inspectActivity(), async () => {
+			closing();
+			await this.closeProcess();
+			closed();
+		}, failed);
+	}
+	/**
+	* Retain this committed process independently of output attachment.
+	* @param signal - physical window stream lifetime.
+	* @returns its hold acknowledgement and lifetime.
+	*/
+	retain(signal) {
+		if (this.retention === void 0) throw new Error("Terminal has not been committed");
+		return this.retention.retain(signal);
+	}
+	/**
 	* Attach with exclusive input control; an older attachment becomes read-only.
 	* @param id - browser attachment identity.
 	* @param signal - attachment cancellation; never terminates the process.
@@ -240,6 +409,7 @@ var BrowserTerminal = class {
 	* @returns when the provider accepts the input.
 	*/
 	write(id, data) {
+		this.retention?.invalidate();
 		return this.enqueue(async () => {
 			this.requireController(id);
 			await this.handle.write(data);
@@ -287,6 +457,16 @@ var BrowserTerminal = class {
 	* @returns after process cleanup and final output drainage; failures remain retryable.
 	*/
 	close() {
+		return this.retention?.close() ?? this.closeProcess();
+	}
+	/**
+	* Stop unattended cleanup scheduling and await final process cleanup.
+	* @returns after terminal and monitor quiescence.
+	*/
+	dispose() {
+		return this.retention?.dispose() ?? this.closeProcess();
+	}
+	closeProcess() {
 		if (this.closing !== void 0) return this.closing;
 		this.closing = (async () => {
 			await this.handle.terminate();
@@ -402,6 +582,7 @@ let TerminalController = (() => {
 	let _shells_decorators;
 	let _list_decorators;
 	let _create_decorators;
+	let _retain_decorators;
 	let _follow_decorators;
 	let _write_decorators;
 	let _resize_decorators;
@@ -414,6 +595,7 @@ let TerminalController = (() => {
 			_shells_decorators = [Remote];
 			_list_decorators = [Remote];
 			_create_decorators = [Remote];
+			_retain_decorators = [Remote({ mode: "stream" })];
 			_follow_decorators = [Remote({ mode: "stream" })];
 			_write_decorators = [Remote];
 			_resize_decorators = [Remote];
@@ -463,6 +645,17 @@ let TerminalController = (() => {
 				},
 				metadata: _metadata
 			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _retain_decorators, {
+				kind: "method",
+				name: "retain",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "retain" in obj,
+					get: (obj) => obj.retain
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
 			__esDecorate(this, null, _follow_decorators, {
 				kind: "method",
 				name: "follow",
@@ -529,7 +722,6 @@ let TerminalController = (() => {
 		static inject = [
 			"subprocess",
 			"sandboxPolicy",
-			"sessionProjections",
 			"typert"
 		];
 		static Config = z.object({
@@ -552,7 +744,10 @@ let TerminalController = (() => {
 			scrollback: z.number().step(1).min(0).default(1e3),
 			maxBufferedBytes: z.number().step(1).min(1024).default(2 * 1024 * 1024),
 			maxInputBytes: z.number().step(1).min(1).default(64 * 1024),
-			disposeGraceMs: z.number().step(1).min(1).default(1e3)
+			disposeGraceMs: z.number().step(1).min(1).default(1e3),
+			unattendedTimeoutMs: z.number().step(1).min(0).max(Number.MAX_SAFE_INTEGER).default(72e5),
+			activityPollIntervalMs: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER).default(3e4),
+			cleanupRetryMs: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER).default(6e4)
 		});
 		owners = /* @__PURE__ */ new Map();
 		lifetime = new AbortController();
@@ -563,15 +758,6 @@ let TerminalController = (() => {
 		constructor(ctx, config) {
 			super(ctx, "terminalController", { namespace: "terminal" });
 			this.config = config;
-			ctx.on("internal/dispatch", (_mode, eventName, args) => {
-				if (eventName !== "session/event") return;
-				const [session, event] = args;
-				if (event.type !== "sandbox/mode") return;
-				const owner = this.owners.get(session.id);
-				if (owner === void 0 || owner.terminals.size + owner.pending.size + owner.allocations.size === 0) return;
-				const current = ctx.sessionProjections.stateOf(session, "sandboxMode") ?? ctx.sandboxPolicy.defaultMode;
-				if (event.data.mode !== current) throw new Error("Close browser terminals before changing the Session sandbox mode");
-			}, { global: true });
 			ctx.effect(() => async () => {
 				this.lifetime.abort(/* @__PURE__ */ new Error("Terminal controller disposed"));
 				const errors = (await Promise.allSettled([...this.owners].map(([id, owner]) => this.disposeOwner(id, owner)))).filter((result) => result.status === "rejected").map((result) => result.reason);
@@ -588,7 +774,7 @@ let TerminalController = (() => {
 			signal.throwIfAborted();
 			const { sandboxPolicy } = this.execution(agent);
 			return {
-				cwd: sandboxPolicy.resolve({ session: agent.session }).workspaceRoot,
+				cwd: agent.session.header.cwd ?? sandboxPolicy.workspaceRoot,
 				maxInputBytes: this.config.maxInputBytes,
 				maxCols: this.config.maxCols,
 				maxRows: this.config.maxRows,
@@ -616,7 +802,7 @@ let TerminalController = (() => {
 			return [...owner.terminals.values(), ...owner.allocations.values()].map((terminal) => terminal.info);
 		}
 		/**
-		* Allocate an interactive shell once for a caller-generated identity.
+		* Allocate a user shell once for a caller-generated identity, without Agent sandbox or approval restrictions.
 		* @param agent - Session owner supplied by the Gateway.
 		* @param request - initial dimensions and idempotency identity.
 		* @param signal - allocation cancellation; committed terminals survive disconnection.
@@ -637,7 +823,6 @@ let TerminalController = (() => {
 				this.requireOpen(owner, request.id);
 				return terminal.info;
 			}
-			if (owner.allocations.has(request.id)) throw new Error("Close the failed terminal allocation before creating it again");
 			if (new Set([
 				...owner.terminals.keys(),
 				...owner.pending.keys(),
@@ -653,6 +838,13 @@ let TerminalController = (() => {
 				const terminal = await allocation;
 				owner.terminals.set(request.id, terminal);
 				owner.allocations.delete(request.id);
+				terminal.monitor(this.config, () => {
+					owner.closedIds.add(request.id);
+				}, () => {
+					owner.terminals.delete(request.id);
+				}, (error) => {
+					this.ctx.logger.error("Browser terminal cleanup failed", error);
+				});
 				this.requireOpen(owner, request.id);
 				return terminal.info;
 			} finally {
@@ -660,6 +852,19 @@ let TerminalController = (() => {
 			}
 		}
 		/**
+		* Retain an existing terminal for a window without activating its Agent or taking input control.
+		* @param sessionId - owning Session identity, including an inactive saved layout.
+		* @param id - retained Host terminal identity.
+		* @param signal - physical Remote stream cancellation.
+		* @returns a hold acknowledgement followed by an open lifetime stream.
+		*/
+		retain(sessionId, id, signal) {
+			const owner = this.owners.get(sessionId);
+			const terminal = owner?.terminals.get(id);
+			if (terminal === void 0 || owner?.closedIds.has(id) === true || owner?.lifetime.signal.aborted === true) throw new RemoteError("terminal/unavailable", "Terminal is closing or unavailable", {});
+			return terminal.retain(signal);
+		}
+		/**
 		* Attach to a terminal without binding its process lifetime to the transport.
 		* @param agent - Session owner supplied by the Gateway.
 		* @param id - terminal identity.
@@ -723,7 +928,7 @@ let TerminalController = (() => {
 			} else {
 				const allocation = owner.allocations.get(id);
 				if (allocation === void 0) return;
-				await allocation.handle.terminate();
+				await allocation.cleanup.close();
 				owner.allocations.delete(id);
 			}
 		}
@@ -750,7 +955,7 @@ let TerminalController = (() => {
 			owner.lifetime.abort(/* @__PURE__ */ new Error("Terminal Session owner disposed"));
 			owner.cleanup = (async () => {
 				await Promise.allSettled(owner.pending.values());
-				const errors = (await Promise.allSettled([...[...owner.terminals.values()].map((terminal) => terminal.close()), ...[...owner.allocations.values()].map((allocation) => allocation.handle.terminate())])).filter((result) => result.status === "rejected").map((result) => result.reason);
+				const errors = (await Promise.allSettled([...[...owner.terminals.values()].map((terminal) => terminal.dispose()), ...[...owner.allocations.values()].map((allocation) => allocation.cleanup.dispose())])).filter((result) => result.status === "rejected").map((result) => result.reason);
 				if (errors.length > 0) throw new AggregateError(errors, "Session terminal cleanup failed");
 				owner.terminals.clear();
 				owner.allocations.clear();
@@ -763,11 +968,12 @@ let TerminalController = (() => {
 		}
 		terminal(agent, id) {
 			const terminal = this.owners.get(agent.id)?.terminals.get(id);
-			if (terminal === void 0) throw new Error("Terminal no longer exists in this Session");
+			if (terminal === void 0) throw new RemoteError("terminal/unavailable", "Terminal no longer exists in this Session", {});
+			this.requireOpen(this.owners.get(agent.id), id);
 			return terminal;
 		}
 		requireOpen(owner, id) {
-			if (owner.closedIds.has(id)) throw new Error("Terminal was closed in this Session");
+			if (owner.closedIds.has(id)) throw new RemoteError("terminal/unavailable", "Terminal was closed in this Session", {});
 		}
 		dimensions(cols, rows) {
 			if (!Number.isSafeInteger(cols) || cols < 2 || cols > this.config.maxCols || !Number.isSafeInteger(rows) || rows < 1 || rows > this.config.maxRows) throw new Error("Terminal dimensions exceed the configured limits");
@@ -783,55 +989,51 @@ let TerminalController = (() => {
 		}
 		async spawn(agent, owner, request, signal) {
 			const environment = this.environment(agent, signal);
-			const { subprocess, sandboxPolicy } = this.execution(agent);
+			const { subprocess } = this.execution(agent);
 			const shell = request.shellPath === void 0 ? await resolveShell(subprocess, this.config.shell, signal) : (await this.shells(agent, signal)).find((candidate) => candidate.path === request.shellPath);
 			if (shell === void 0) throw new Error("Selected shell is not available in this execution environment");
-			const policy = sandboxPolicy.resolve({ session: agent.session });
-			let argv = [shell.path, ...shell.args];
-			if (policy.mode !== "danger-full-access") {
-				const sandbox = agent.ctx.get("sandbox");
-				if (sandbox === void 0) throw new Error("The Session sandbox mode requires an execution sandbox provider");
-				argv = (await sandbox.confine(argv, {
-					...policy,
-					mode: policy.mode
-				}, signal)).argv;
-			}
 			const handle = await subprocess.spawnTerminal({
-				argv,
+				argv: [shell.path, ...shell.args],
 				cwd: environment.cwd,
 				cols: request.cols,
 				rows: request.rows,
 				terminalType: "xterm-256color",
 				env: { DSH_SESSION_ID: agent.id },
+				shellActivity: true,
 				graceMs: this.config.disposeGraceMs,
 				signal
 			});
-			const allocation = {
-				handle,
-				info: {
-					id: request.id,
-					shell,
-					title: shell.name,
-					cwd: environment.cwd,
-					cols: request.cols,
-					rows: request.rows,
-					state: "running",
-					exitCode: null
-				}
+			const info = {
+				id: request.id,
+				shell,
+				title: shell.name,
+				cwd: environment.cwd,
+				cols: request.cols,
+				rows: request.rows,
+				state: "running",
+				exitCode: null
 			};
-			owner.allocations.set(request.id, allocation);
 			try {
 				signal.throwIfAborted();
-				return new BrowserTerminal(handle, allocation.info, this.config.scrollback, this.config.maxBufferedBytes);
+				return new BrowserTerminal(handle, info, this.config.scrollback, this.config.maxBufferedBytes);
 			} catch (error) {
-				allocation.info = {
-					...allocation.info,
-					state: "failed",
-					error: error instanceof Error ? error.message : String(error)
-				};
-				try {
+				const cleanup = new TerminalRetention(this.config, handle.inspectActivity.bind(handle), async () => {
+					owner.closedIds.add(request.id);
 					await handle.terminate();
 					owner.allocations.delete(request.id);
+				}, (cleanupError) => {
+					this.ctx.logger.error("Browser terminal allocation cleanup failed", cleanupError);
+				});
+				owner.allocations.set(request.id, {
+					info: {
+						...info,
+						state: "failed",
+						error: error instanceof Error ? error.message : String(error)
+					},
+					cleanup
+				});
+				try {
+					await cleanup.close();
 				} catch (cleanupError) {
 					throw new AggregateError([error, cleanupError], "Terminal allocation cleanup failed");
 				}