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

package/lib/index.js

@@ -0,0 +1,844 @@
+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 { Deque } from "@deepseek-ai/dsh-deque";
+//#region lib/types/shells.js
+/** Shell selection and executable verification use the target execution provider. */
+/**
+* Resolve the configured shell or the execution environment's default shell.
+* @param subprocess - target execution provider.
+* @param configured - optional profile overriding the environment's default shell.
+* @param signal - resolution cancellation.
+* @returns one verified shell; a declared default that cannot resolve rejects.
+*/
+async function resolveShell(subprocess, configured, signal) {
+	let shell = configured;
+	if (shell === void 0) {
+		const environment = await subprocess.terminalEnvironment(signal);
+		shell = profile(environment.defaultShell ?? (environment.platform === "windows" ? "cmd.exe" : "/bin/sh"));
+	}
+	const path = await subprocess.resolveExecutable(shell.path, void 0, signal);
+	return {
+		...shell,
+		path
+	};
+}
+function profile(path) {
+	const name = path.slice(Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\")) + 1);
+	const kind = name.toLowerCase().replace(/\.exe$/u, "");
+	return {
+		path,
+		name,
+		args: kind === "cmd" ? [] : kind === "pwsh" || kind === "powershell" ? ["-NoLogo"] : ["-i"]
+	};
+}
+/**
+* List verified candidates after the configured or environment-default shell.
+* @param subprocess - target execution provider.
+* @param configured - optional default profile.
+* @param candidates - executable names or paths permitted for shell selection.
+* @param signal - discovery cancellation.
+* @returns unique installed shells, with the default first; transport failures reject.
+*/
+async function discoverShells(subprocess, configured, candidates, signal) {
+	const preferred = await resolveShell(subprocess, configured, signal);
+	const found = await Promise.all(candidates.map(async (candidate) => {
+		try {
+			return await resolveShell(subprocess, profile(candidate), signal);
+		} catch (error) {
+			if (error instanceof SubprocessExecutableNotFoundError) return void 0;
+			throw error;
+		}
+	}));
+	const shells = /* @__PURE__ */ new Map();
+	for (const shell of [preferred, ...found]) {
+		if (shell === void 0) continue;
+		const key = shell.path.includes("\\") ? shell.path.toLowerCase() : shell.path;
+		if (!shells.has(key)) shells.set(key, shell);
+	}
+	return [...shells.values()];
+}
+//#endregion
+//#region lib/types/stream.js
+/** A bounded output queue for one Remote stream generation. */
+/** Slow followers fail explicitly; a later attachment recovers from the screen. */
+var TerminalFollower = class {
+	maxBytes;
+	queue = new Deque();
+	bytes = 0;
+	wake;
+	closed = false;
+	finished = false;
+	failure;
+	/** @param maxBytes - maximum queued UTF-8 bytes for this follower. */
+	constructor(maxBytes) {
+		this.maxBytes = maxBytes;
+	}
+	/**
+	* Queue a frame or fail this follower when its byte limit is exceeded.
+	* @param frame - next ordered frame.
+	*/
+	push(frame) {
+		if (this.closed || this.finished) return;
+		const bytes = Buffer.byteLength(JSON.stringify(frame), "utf8");
+		if (this.bytes + bytes > this.maxBytes) {
+			this.failure = /* @__PURE__ */ new Error("Terminal output consumer exceeded its buffer; reconnect to recover the current screen");
+			this.close();
+			return;
+		}
+		this.queue.pushBack({
+			frame,
+			bytes
+		});
+		this.bytes += bytes;
+		this.wake?.();
+	}
+	/** Finish after delivering every queued frame, including the final exit state. */
+	finish() {
+		this.finished = true;
+		this.wake?.();
+	}
+	/** Stop this follower without stopping its terminal. */
+	close() {
+		this.closed = true;
+		this.queue.clear();
+		this.bytes = 0;
+		this.wake?.();
+	}
+	/**
+	* Drain until detached or failed.
+	* @param signal - Remote generation cancellation.
+	* @returns ordered terminal frames.
+	*/
+	async *read(signal) {
+		const abort = () => {
+			this.close();
+		};
+		signal.addEventListener("abort", abort, { once: true });
+		if (signal.aborted) abort();
+		try {
+			while (!this.closed) {
+				const next = this.queue.popFront();
+				if (next !== void 0) {
+					this.bytes -= next.bytes;
+					yield next.frame;
+				} else {
+					if (this.finished) break;
+					await new Promise((resolve) => {
+						this.wake = resolve;
+					});
+					this.wake = void 0;
+				}
+			}
+			if (this.failure !== void 0) throw this.failure;
+		} finally {
+			signal.removeEventListener("abort", abort);
+			this.close();
+		}
+	}
+};
+//#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
+	};
+}
+/** Process lifetime is independent of follower and component lifetimes. */
+var BrowserTerminal = class {
+	handle;
+	info;
+	maxBufferedBytes;
+	screen;
+	serializer;
+	followers = /* @__PURE__ */ new Set();
+	sequence = 0;
+	operations = Promise.resolve();
+	drained;
+	closing;
+	controller;
+	/**
+	* @param handle - allocated terminal process range.
+	* @param info - initial metadata.
+	* @param scrollback - maximum retained scrollback rows.
+	* @param maxBufferedBytes - per-follower queue cap.
+	*/
+	constructor(handle, info, scrollback, maxBufferedBytes) {
+		this.handle = handle;
+		this.info = info;
+		this.maxBufferedBytes = maxBufferedBytes;
+		this.screen = new Terminal({
+			cols: info.cols,
+			rows: info.rows,
+			scrollback,
+			allowProposedApi: true
+		});
+		this.serializer = new SerializeAddon();
+		this.screen.loadAddon(this.serializer);
+		this.drained = this.consume();
+	}
+	/**
+	* Attach with exclusive input control; an older attachment becomes read-only.
+	* @param id - browser attachment identity.
+	* @param signal - attachment cancellation; never terminates the process.
+	* @returns a consistent screen followed by ordered output and state changes.
+	*/
+	async *follow(id, signal) {
+		signal.throwIfAborted();
+		const follower = new TerminalFollower(this.maxBufferedBytes);
+		const baseline = await this.enqueue(() => {
+			signal.throwIfAborted();
+			this.controller = {
+				id,
+				follower
+			};
+			this.info = {
+				...this.info,
+				controllerId: id
+			};
+			this.broadcast({
+				type: "state",
+				info: this.info
+			});
+			const snapshot = {
+				type: "snapshot",
+				sequence: this.sequence,
+				screen: this.serializer.serialize(),
+				info: this.info
+			};
+			this.followers.add(follower);
+			return snapshot;
+		});
+		try {
+			yield baseline;
+			yield* follower.read(signal);
+		} finally {
+			this.followers.delete(follower);
+			follower.close();
+			if (this.controller?.follower === follower) {
+				this.controller = void 0;
+				const { controllerId: _controllerId, ...info } = this.info;
+				this.info = info;
+				this.broadcast({
+					type: "state",
+					info
+				});
+			}
+		}
+	}
+	/**
+	* Send raw terminal input without command interpretation.
+	* @param id - current writable attachment.
+	* @param data - UTF-8 input, including shell completion/control keys.
+	* @returns when the provider accepts the input.
+	*/
+	write(id, data) {
+		return this.enqueue(async () => {
+			this.requireController(id);
+			await this.handle.write(data);
+		});
+	}
+	/**
+	* Resize the PTY and recovery screen in the same operation order as output.
+	* @param id - current writable attachment.
+	* @param cols - validated column count.
+	* @param rows - validated row count.
+	* @returns when the provider and emulator use the new dimensions.
+	*/
+	resize(id, cols, rows) {
+		return this.enqueue(async () => {
+			this.requireController(id);
+			await this.handle.resize(cols, rows);
+			this.screen.resize(cols, rows);
+			this.info = {
+				...this.info,
+				cols,
+				rows
+			};
+			this.broadcast({
+				type: "state",
+				info: this.info
+			});
+		});
+	}
+	/**
+	* Publish a display name to every attached view.
+	* @param title - validated user title.
+	*/
+	rename(title) {
+		this.info = {
+			...this.info,
+			title
+		};
+		this.broadcast({
+			type: "state",
+			info: this.info
+		});
+	}
+	/**
+	* Terminate the complete provider-owned process range before releasing its screen.
+	* @returns after process cleanup and final output drainage; failures remain retryable.
+	*/
+	close() {
+		if (this.closing !== void 0) return this.closing;
+		this.closing = (async () => {
+			await this.handle.terminate();
+			await this.drained;
+			for (const follower of this.followers) follower.finish();
+			this.followers.clear();
+			this.screen.dispose();
+		})().catch((error) => {
+			this.closing = void 0;
+			throw error;
+		});
+		return this.closing;
+	}
+	requireController(id) {
+		if (this.closing !== void 0 || this.info.state !== "running") throw new RemoteError("terminal/control-unavailable", "Terminal is not running", { reason: "not-running" });
+		if (this.controller?.id !== id) throw new RemoteError("terminal/control-unavailable", "Terminal input is controlled by another attachment", { reason: "read-only" });
+	}
+	broadcast(frame) {
+		for (const follower of this.followers) follower.push(frame);
+	}
+	enqueue(operation) {
+		const pending = this.operations.then(operation);
+		this.operations = pending.catch(() => {});
+		return pending;
+	}
+	async consume() {
+		const decoder = new TextDecoder("utf-8", { ignoreBOM: true });
+		const outcome = this.handle.done.then((value) => ({ value }), (error) => ({ error }));
+		try {
+			for await (const chunk of this.handle.output) {
+				const data = decoder.decode(chunk, { stream: true });
+				await this.output(data);
+			}
+			await this.output(decoder.decode());
+			const result = await outcome;
+			if ("error" in result) throw result.error;
+			this.info = {
+				...this.info,
+				state: "exited",
+				exitCode: result.value.exitCode
+			};
+		} catch (error) {
+			this.info = {
+				...this.info,
+				state: "failed",
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+		this.broadcast({
+			type: "state",
+			info: this.info
+		});
+	}
+	async output(data) {
+		if (data.length === 0) return;
+		await this.enqueue(async () => {
+			await new Promise((resolve) => {
+				this.screen.write(data, resolve);
+			});
+			this.broadcast({
+				type: "output",
+				sequence: ++this.sequence,
+				data
+			});
+		});
+	}
+};
+//#endregion
+//#region lib/types/index.js
+var __runInitializers = function(thisArg, initializers, value) {
+	var useValue = arguments.length > 2;
+	for (var i = 0; i < initializers.length; i++) value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+	return useValue ? value : void 0;
+};
+var __esDecorate = function(ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+	function accept(f) {
+		if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected");
+		return f;
+	}
+	var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+	var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+	var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+	var _, done = false;
+	for (var i = decorators.length - 1; i >= 0; i--) {
+		var context = {};
+		for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+		for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+		context.addInitializer = function(f) {
+			if (done) throw new TypeError("Cannot add initializers after decoration has completed");
+			extraInitializers.push(accept(f || null));
+		};
+		var result = (0, decorators[i])(kind === "accessor" ? {
+			get: descriptor.get,
+			set: descriptor.set
+		} : descriptor[key], context);
+		if (kind === "accessor") {
+			if (result === void 0) continue;
+			if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+			if (_ = accept(result.get)) descriptor.get = _;
+			if (_ = accept(result.set)) descriptor.set = _;
+			if (_ = accept(result.init)) initializers.unshift(_);
+		} else if (_ = accept(result)) if (kind === "field") initializers.unshift(_);
+		else descriptor[key] = _;
+	}
+	if (target) Object.defineProperty(target, contextIn.name, descriptor);
+	done = true;
+};
+/** Typed Remote control of transient Session-owned terminal processes. */
+let TerminalController = (() => {
+	let _classSuper = TypertRemoteService;
+	let _instanceExtraInitializers = [];
+	let _environment_decorators;
+	let _shells_decorators;
+	let _list_decorators;
+	let _create_decorators;
+	let _follow_decorators;
+	let _write_decorators;
+	let _resize_decorators;
+	let _rename_decorators;
+	let _close_decorators;
+	return class TerminalController extends _classSuper {
+		static {
+			const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+			_environment_decorators = [Remote];
+			_shells_decorators = [Remote];
+			_list_decorators = [Remote];
+			_create_decorators = [Remote];
+			_follow_decorators = [Remote({ mode: "stream" })];
+			_write_decorators = [Remote];
+			_resize_decorators = [Remote];
+			_rename_decorators = [Remote];
+			_close_decorators = [Remote];
+			__esDecorate(this, null, _environment_decorators, {
+				kind: "method",
+				name: "environment",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "environment" in obj,
+					get: (obj) => obj.environment
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _shells_decorators, {
+				kind: "method",
+				name: "shells",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "shells" in obj,
+					get: (obj) => obj.shells
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _list_decorators, {
+				kind: "method",
+				name: "list",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "list" in obj,
+					get: (obj) => obj.list
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _create_decorators, {
+				kind: "method",
+				name: "create",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "create" in obj,
+					get: (obj) => obj.create
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _follow_decorators, {
+				kind: "method",
+				name: "follow",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "follow" in obj,
+					get: (obj) => obj.follow
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _write_decorators, {
+				kind: "method",
+				name: "write",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "write" in obj,
+					get: (obj) => obj.write
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _resize_decorators, {
+				kind: "method",
+				name: "resize",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "resize" in obj,
+					get: (obj) => obj.resize
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _rename_decorators, {
+				kind: "method",
+				name: "rename",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "rename" in obj,
+					get: (obj) => obj.rename
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _close_decorators, {
+				kind: "method",
+				name: "close",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "close" in obj,
+					get: (obj) => obj.close
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			if (_metadata) Object.defineProperty(this, Symbol.metadata, {
+				enumerable: true,
+				configurable: true,
+				writable: true,
+				value: _metadata
+			});
+		}
+		config = __runInitializers(this, _instanceExtraInitializers);
+		static inject = [
+			"subprocess",
+			"sandboxPolicy",
+			"sessionProjections",
+			"typert"
+		];
+		static Config = z.object({
+			shell: z.union([z.object({
+				path: z.string().required(),
+				name: z.string().required(),
+				args: z.array(z.string()).default([])
+			}), z.const(void 0)]),
+			shellCandidates: z.array(z.string().min(1)).default([
+				"zsh",
+				"bash",
+				"fish",
+				"pwsh",
+				"powershell",
+				"cmd"
+			]),
+			maxTerminals: z.number().step(1).min(1).default(8),
+			maxCols: z.number().step(1).min(2).default(500),
+			maxRows: z.number().step(1).min(1).default(200),
+			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)
+		});
+		owners = /* @__PURE__ */ new Map();
+		lifetime = new AbortController();
+		/**
+		* @param ctx - Host context carrying typed Remote and execution providers.
+		* @param config - validated terminal limits and optional shell profile.
+		*/
+		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);
+				if (errors.length > 0) throw new AggregateError(errors, "Browser terminal cleanup failed");
+			}, "terminal-controller.processes");
+		}
+		/**
+		* Read the Session working directory and terminal limits without resolving a shell.
+		* @param agent - Session owner supplied by the Gateway.
+		* @param signal - request cancellation.
+		* @returns the Session workspace directory and terminal limits.
+		*/
+		environment(agent, signal) {
+			signal.throwIfAborted();
+			const { sandboxPolicy } = this.execution(agent);
+			return {
+				cwd: sandboxPolicy.resolve({ session: agent.session }).workspaceRoot,
+				maxInputBytes: this.config.maxInputBytes,
+				maxCols: this.config.maxCols,
+				maxRows: this.config.maxRows,
+				scrollback: this.config.scrollback
+			};
+		}
+		/**
+		* Discover installed shells in the Session's execution environment.
+		* @param agent - Session owner supplied by the Gateway.
+		* @param signal - request cancellation.
+		* @returns verified profiles, with the configured or system default first.
+		*/
+		shells(agent, signal) {
+			signal.throwIfAborted();
+			return discoverShells(this.execution(agent).subprocess, this.config.shell, this.config.shellCandidates, signal);
+		}
+		/**
+		* List retained terminals without resolving or activating an Agent.
+		* @param sessionId - displayed Session identity, including offline history.
+		* @returns terminals retained for this Host lifetime.
+		*/
+		list(sessionId) {
+			const owner = this.owners.get(sessionId);
+			if (owner === void 0) return [];
+			return [...owner.terminals.values(), ...owner.allocations.values()].map((terminal) => terminal.info);
+		}
+		/**
+		* Allocate an interactive shell once for a caller-generated identity.
+		* @param agent - Session owner supplied by the Gateway.
+		* @param request - initial dimensions and idempotency identity.
+		* @param signal - allocation cancellation; committed terminals survive disconnection.
+		* @returns the existing or newly committed terminal.
+		*/
+		async create(agent, request, signal) {
+			this.lifetime.signal.throwIfAborted();
+			if (!/^[\w-]{1,128}$/u.test(request.id)) throw new Error("Invalid terminal identity");
+			this.dimensions(request.cols, request.rows);
+			const owner = this.owner(agent);
+			owner.lifetime.signal.throwIfAborted();
+			this.requireOpen(owner, request.id);
+			const existing = owner.terminals.get(request.id);
+			if (existing !== void 0) return existing.info;
+			const pending = owner.pending.get(request.id);
+			if (pending !== void 0) {
+				const terminal = await pending;
+				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(),
+				...owner.allocations.keys()
+			]).size >= this.config.maxTerminals) throw new RemoteError("terminal/limit-reached", "Session terminal limit reached", { limit: this.config.maxTerminals });
+			const allocation = this.spawn(agent, owner, request, AbortSignal.any([
+				signal,
+				this.lifetime.signal,
+				owner.lifetime.signal
+			]));
+			owner.pending.set(request.id, allocation);
+			try {
+				const terminal = await allocation;
+				owner.terminals.set(request.id, terminal);
+				owner.allocations.delete(request.id);
+				this.requireOpen(owner, request.id);
+				return terminal.info;
+			} finally {
+				owner.pending.delete(request.id);
+			}
+		}
+		/**
+		* Attach to a terminal without binding its process lifetime to the transport.
+		* @param agent - Session owner supplied by the Gateway.
+		* @param id - terminal identity.
+		* @param attachmentId - new exclusive input attachment.
+		* @param signal - physical stream cancellation.
+		* @returns screen recovery followed by output and metadata changes.
+		*/
+		follow(agent, id, attachmentId, signal) {
+			if (!/^[\w-]{1,128}$/u.test(attachmentId)) throw new Error("Invalid terminal attachment identity");
+			return this.terminal(agent, id).follow(attachmentId, signal);
+		}
+		/**
+		* Deliver raw input, including Tab completion and control characters.
+		* @param agent - Session owner supplied by the Gateway.
+		* @param id - terminal identity.
+		* @param attachmentId - current writable attachment.
+		* @param data - input bytes represented as UTF-8 text.
+		* @returns after provider input acceptance.
+		*/
+		async write(agent, id, attachmentId, data) {
+			if (Buffer.byteLength(data, "utf8") > this.config.maxInputBytes) throw new Error("Terminal input exceeds the configured limit");
+			await this.terminal(agent, id).write(attachmentId, data);
+		}
+		/**
+		* Update the dimensions of the PTY and recovery screen.
+		* @param agent - Session owner supplied by the Gateway.
+		* @param id - terminal identity.
+		* @param attachmentId - current writable attachment.
+		* @param cols - column count.
+		* @param rows - row count.
+		* @returns after the resize completes.
+		*/
+		async resize(agent, id, attachmentId, cols, rows) {
+			this.dimensions(cols, rows);
+			await this.terminal(agent, id).resize(attachmentId, cols, rows);
+		}
+		/**
+		* Rename a terminal without changing its shell.
+		* @param agent - Session owner supplied by the Gateway.
+		* @param id - terminal identity.
+		* @param title - nonempty display title, at most 120 characters.
+		*/
+		rename(agent, id, title) {
+			if (title.trim().length === 0 || title.length > 120) throw new Error("Terminal title must contain 1–120 characters");
+			this.terminal(agent, id).rename(title.trim());
+		}
+		/**
+		* Close an identity to future creation and kill its process range; repeated closes succeed.
+		* @param agent - Session owner supplied by the Gateway.
+		* @param id - terminal identity.
+		* @returns after provider cleanup succeeds. A failure retains the terminal for retry.
+		*/
+		async close(agent, id) {
+			const owner = this.owner(agent);
+			owner.closedIds.add(id);
+			await owner.pending.get(id)?.catch(() => {});
+			const terminal = owner.terminals.get(id);
+			if (terminal !== void 0) {
+				await terminal.close();
+				owner.terminals.delete(id);
+			} else {
+				const allocation = owner.allocations.get(id);
+				if (allocation === void 0) return;
+				await allocation.handle.terminate();
+				owner.allocations.delete(id);
+			}
+		}
+		owner(agent) {
+			let owner = this.owners.get(agent.id);
+			if (owner === void 0) {
+				owner = {
+					terminals: /* @__PURE__ */ new Map(),
+					pending: /* @__PURE__ */ new Map(),
+					allocations: /* @__PURE__ */ new Map(),
+					closedIds: /* @__PURE__ */ new Set(),
+					lifetime: new AbortController()
+				};
+				this.owners.set(agent.id, owner);
+				const owned = owner;
+				agent.ctx.effect(() => async () => {
+					await this.disposeOwner(agent.id, owned);
+				}, "terminal-controller.owner");
+			}
+			return owner;
+		}
+		disposeOwner(id, owner) {
+			if (owner.cleanup !== void 0) return owner.cleanup;
+			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);
+				if (errors.length > 0) throw new AggregateError(errors, "Session terminal cleanup failed");
+				owner.terminals.clear();
+				owner.allocations.clear();
+				this.owners.delete(id);
+			})().catch((error) => {
+				delete owner.cleanup;
+				throw error;
+			});
+			return owner.cleanup;
+		}
+		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");
+			return terminal;
+		}
+		requireOpen(owner, id) {
+			if (owner.closedIds.has(id)) throw new Error("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");
+		}
+		execution(agent) {
+			const subprocess = agent.ctx.get("subprocess");
+			const sandboxPolicy = agent.ctx.get("sandboxPolicy");
+			if (subprocess === void 0 || sandboxPolicy === void 0) throw new Error("The Session execution environment requires subprocess and sandbox policy providers");
+			return {
+				subprocess,
+				sandboxPolicy
+			};
+		}
+		async spawn(agent, owner, request, signal) {
+			const environment = this.environment(agent, signal);
+			const { subprocess, sandboxPolicy } = 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,
+				cwd: environment.cwd,
+				cols: request.cols,
+				rows: request.rows,
+				terminalType: "xterm-256color",
+				env: { DSH_SESSION_ID: agent.id },
+				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
+				}
+			};
+			owner.allocations.set(request.id, allocation);
+			try {
+				signal.throwIfAborted();
+				return new BrowserTerminal(handle, allocation.info, this.config.scrollback, this.config.maxBufferedBytes);
+			} catch (error) {
+				allocation.info = {
+					...allocation.info,
+					state: "failed",
+					error: error instanceof Error ? error.message : String(error)
+				};
+				try {
+					await handle.terminate();
+					owner.allocations.delete(request.id);
+				} catch (cleanupError) {
+					throw new AggregateError([error, cleanupError], "Terminal allocation cleanup failed");
+				}
+				throw error;
+			}
+		}
+	};
+})();
+//#endregion
+export { TerminalController, TerminalController as default };