From 502893a35a6e1be0b64cc60489316bcca93d7b2f Mon Sep 17 00:00:00 2001 From: QQ Date: Sat, 14 Nov 2026 14:57:11 +0800 Subject: [PATCH] Import packages/plugin/src/remote-terminal-controller.ts --- .../plugin/src/remote-terminal-controller.ts | 392 ++++++++++++++++++ 1 file changed, 392 insertions(+) create mode 100644 packages/plugin/src/remote-terminal-controller.ts diff --git a/packages/plugin/src/remote-terminal-controller.ts b/packages/plugin/src/remote-terminal-controller.ts new file mode 100644 index 0000000..2be390f --- /dev/null +++ b/packages/plugin/src/remote-terminal-controller.ts @@ -0,0 +1,392 @@ +import headless from '@xterm/headless' +import serialize from '@xterm/addon-serialize' +import type { Terminal } from '@xterm/headless' +import { RpcError } from './safe-error.js' +import type { TypertRpcResult } from './typert-gateway-contract.js' +import { discoverTerminalShells, type RemoteTerminalProcess, type RemoteTerminalSpawner, type TerminalShell } from './remote-terminal-provider.js' + +const MAX_INPUT_BYTES = 64 * 1024 +const MAX_COLS = 240 +const MAX_ROWS = 100 +const MAX_TERMINALS = 256 +const MAX_SESSION_TERMINALS = 8 +const SCROLLBACK = 1000 +const MAX_SNAPSHOT_BYTES = 256 * 1024 +const MAX_FOLLOWER_BYTES = 1024 * 1024 +const IDLE_TIMEOUT_MS = 2 * 60 * 60 * 1000 +const POLL_MS = 30_000 + +type Frame = Record +type ScopeError = (code: string, message: string) => RpcError + +/** Slow followers fail; detaching never keeps an unbounded output journal. */ +class TerminalFollower implements AsyncIterable { + private values: Array<{ value: Frame; bytes: number }> = [] + private bytes = 0 + private wake?: () => void + private finished = false + private closed = false + private failure?: Error + constructor(private readonly detach: () => void) {} + push(value: Frame): void { + if (this.closed || this.finished) return + const bytes = Buffer.byteLength(JSON.stringify(value)) + if (this.bytes + bytes > MAX_FOLLOWER_BYTES) { + this.failure = new RpcError('TERMINAL_BUFFER_EXCEEDED', 'Terminal output fell behind. Reconnect to recover the screen.') + this.close() + return + } + this.bytes += bytes + this.values.push({ value, bytes }) + this.wake?.() + } + finish(): void { this.finished = true; this.wake?.() } + close(): void { + if (this.closed) return + this.closed = true; this.values = []; this.bytes = 0 + this.detach(); this.wake?.() + } + async *[Symbol.asyncIterator](): AsyncIterator { + try { + while (!this.closed) { + const next = this.values.shift() + if (next) { this.bytes -= next.bytes; yield next.value } + else if (this.finished) break + else await new Promise(resolve => { this.wake = resolve }) + } + if (this.failure) throw this.failure + } finally { this.close() } + } +} + +/** One Host-owned terminal. All screen/output/input transitions are serialized. */ +class OwnedTerminal { + readonly allocation = new AbortController() + readonly screen: Terminal + private readonly serializer = new serialize.SerializeAddon() + readonly followers = new Set() + readonly holders = new Set() + pending?: Promise + process?: RemoteTerminalProcess + shell?: TerminalShell + title = '' + controller?: TerminalFollower + controllerId?: string + sequence = 0 + state: 'running' | 'exited' | 'failed' = 'running' + exitCode: number | null = null + error?: string + closing = false + private disposed = false + private operations = Promise.resolve() + private cleanup?: Promise + private timer?: ReturnType + private idle?: { since: number; revision: number; observedAt: number } + private activityEpoch = 0 + + constructor(readonly sessionId: string, readonly id: string, readonly cwd: string, + public cols: number, public rows: number, private readonly removed: () => void) { + this.screen = new headless.Terminal({ cols, rows, scrollback: SCROLLBACK, allowProposedApi: true }) + this.screen.loadAddon(this.serializer) + } + + info(): Frame { + return { id: this.id, title: this.title, shell: this.shell && { ...this.shell, args: [...this.shell.args] }, + cwd: this.cwd, cols: this.cols, rows: this.rows, state: this.state, exitCode: this.exitCode, + ...(this.error === undefined ? {} : { error: this.error }), + ...(this.controllerId === undefined ? {} : { controllerId: this.controllerId }) } + } + + enqueue(operation: () => T | Promise): Promise { + const result = this.operations.then(operation) + this.operations = result.then(() => undefined, () => undefined) + return result + } + + emit(value: Frame): void { for (const follower of this.followers) follower.push(value) } + invalidate(): void { this.activityEpoch++; this.idle = undefined } + + async pump(): Promise { + const process = this.process! + // Register the rejection handler immediately, even while output is still open. + const outcome = process.completed.then(value => ({ value }), () => ({ value: undefined })) + let failed = false + try { + for await (const chunk of process.output) { + // Bound each wire frame and preserve UTF-16 surrogate pairs across splits. + for (let start = 0; start < chunk.length;) { + let end = Math.min(start + 16_384, chunk.length) + if (end < chunk.length && /[\uD800-\uDBFF]/u.test(chunk[end - 1]!)) end-- + const data = chunk.slice(start, end); start = end + await this.enqueue(async () => { + if (this.disposed) return + await new Promise(resolve => this.screen.write(data, resolve)) + this.sequence++ + this.emit({ type: 'output', sequence: this.sequence, data }) + }) + } + } + } catch { failed = true } + if (failed) { + await this.enqueue(() => { + if (this.disposed) return + this.state = 'failed'; this.error = 'The terminal output stream failed.' + this.emit({ type: 'state', info: this.info() }) + }) + await this.close().catch(() => undefined) + return + } + const ended = await outcome + await this.enqueue(() => { + if (this.disposed) return + this.exitCode = ended.value?.exitCode ?? null + if (failed || ended.value === undefined) { this.state = 'failed'; this.error = 'The terminal process or output stream failed.' } + else this.state = 'exited' + this.emit({ type: 'state', info: this.info() }) + for (const follower of this.followers) follower.finish() + }) + } + + snapshot(): string { + let lines = SCROLLBACK + let screen = this.serializer.serialize({ scrollback: lines }) + while (Buffer.byteLength(screen) > MAX_SNAPSHOT_BYTES && lines > 0) { + lines = Math.floor(lines / 2) + screen = this.serializer.serialize({ scrollback: lines }) + } + if (Buffer.byteLength(screen) > MAX_SNAPSHOT_BYTES) throw new RpcError('TERMINAL_BUFFER_EXCEEDED', 'The terminal screen exceeds the recovery limit.') + return screen + } + + monitor(): void { + if (this.timer || this.disposed || (!this.closing && !this.process?.inspectActivity)) return + this.timer = setTimeout(() => { + this.timer = undefined + void this.observe().finally(() => this.monitor()) + }, POLL_MS) + this.timer.unref() + } + private async observe(): Promise { + if (this.closing) { await this.close().catch(() => undefined); return } + if (this.holders.size || this.followers.size) { this.invalidate(); return } + const epoch = this.activityEpoch + try { + const activity = await this.process!.inspectActivity!() + if (this.disposed || epoch !== this.activityEpoch) return + if (activity.state !== 'idle') { this.idle = undefined; return } + const now = performance.now() + if (this.idle?.revision !== activity.revision || now - this.idle.observedAt > POLL_MS * 2) this.idle = { since: now, revision: activity.revision, observedAt: now } + else { + this.idle.observedAt = now + if (now - this.idle.since >= IDLE_TIMEOUT_MS) await this.close() + } + } catch { this.idle = undefined } + } + + /** Failed cleanup remains owned and closed to input, allowing a later retry. */ + close(): Promise { + if (this.cleanup) return this.cleanup + this.closing = true; this.invalidate(); this.allocation.abort() + this.cleanup = (async () => { + await this.pending?.catch(() => undefined) + await this.process?.terminate() + await this.enqueue(() => { + if (this.disposed) return + this.disposed = true + if (this.timer) clearTimeout(this.timer) + this.state = 'exited' + this.emit({ type: 'state', info: this.info() }) + for (const follower of [...this.followers, ...this.holders]) follower.finish() + this.screen.dispose() + this.removed() + }) + })().catch(() => { + this.cleanup = undefined + this.state = 'failed'; this.error = 'Terminal cleanup failed. Close the terminal again to retry.' + this.emit({ type: 'state', info: this.info() }) + this.monitor() + throw new RpcError('TERMINAL_CLEANUP_FAILED', 'The terminal process could not be fully stopped. Retry closing it.') + }) + return this.cleanup + } +} + +/** Shared across encrypted connections; backend disposal also fences pending creations. */ +export class RemoteTerminalState { + readonly terminals = new Map() + revision = 0 + constructor(readonly onRemoved: (key: string) => void = () => {}) {} + async dispose(matches: (sessionId: string) => boolean = () => true): Promise { + this.revision++ + const results = await Promise.allSettled([...this.terminals.values()].filter(terminal => matches(terminal.sessionId)).map(terminal => terminal.close())) + if (results.some(result => result.status === 'rejected')) throw new RpcError('TERMINAL_CLEANUP_FAILED', 'Some terminal processes could not be stopped. Retry cleanup.') + } +} + +/** Official terminal shapes over backend-owned IDs, without creating Harness Agents. */ +export class RemoteTerminalController { + private readonly subscriptions = new Set() + constructor(private readonly shared: RemoteTerminalState, private readonly spawn: RemoteTerminalSpawner, + private readonly enabled: () => boolean, private readonly scopeError: ScopeError) {} + + async call(endpoint: string, sessionId: string, cwd: string, args: Record, signal: AbortSignal): Promise { + this.check(signal) + if (endpoint === 'terminal/environment') return { ok: true, value: { cwd, maxInputBytes: MAX_INPUT_BYTES, maxCols: MAX_COLS, maxRows: MAX_ROWS, scrollback: SCROLLBACK } } + if (endpoint === 'terminal/shells') return { ok: true, value: await this.shells(signal) } + if (endpoint === 'terminal/list') return { ok: true, value: [...this.shared.terminals.values()].filter(item => item.sessionId === sessionId && item.shell && item.process).map(item => item.info()) } + if (endpoint === 'terminal/create') return { ok: true, value: await this.create(sessionId, cwd, args, signal) } + const id = identifier(args.id) + if (endpoint === 'terminal/close') { await this.shared.terminals.get(`${sessionId}/${id}`)?.close(); return { ok: true } } + const terminal = this.requireTerminal(sessionId, id) + await terminal.enqueue(async () => { + this.check(signal) + if (terminal.closing) throw this.scopeError('TERMINAL_NOT_FOUND', 'The terminal is closing.') + if (endpoint === 'terminal/rename') { + if (typeof args.title !== 'string' || !args.title.trim() || args.title.length > 120) throw new RpcError('INVALID_MESSAGE', 'The terminal title is invalid.') + terminal.title = args.title.trim() + terminal.emit({ type: 'state', info: terminal.info() }) + return + } + if (endpoint !== 'terminal/write' && endpoint !== 'terminal/resize') throw new RpcError('METHOD_NOT_FOUND', 'The terminal method does not exist.') + if (identifier(args.attachmentId) !== terminal.controllerId || !terminal.controller + || !this.subscriptions.has(terminal.controller) || terminal.state !== 'running') throw new RpcError('PERMISSION_DENIED', 'This attachment does not own terminal input.') + terminal.invalidate() + if (endpoint === 'terminal/write') { + if (typeof args.data !== 'string' || Buffer.byteLength(args.data) > MAX_INPUT_BYTES) throw new RpcError('INVALID_MESSAGE', 'Terminal input is invalid or too large.') + await terminal.process!.write(args.data) + } else { + const cols = dimension(args.cols, MAX_COLS), rows = dimension(args.rows, MAX_ROWS) + await terminal.process!.resize(cols, rows) + terminal.screen.resize(cols, rows); terminal.cols = cols; terminal.rows = rows + terminal.emit({ type: 'state', info: terminal.info() }) + } + }) + return { ok: true } + } + + async open(endpoint: string, sessionId: string, args: Record, signal: AbortSignal): Promise> { + this.check(signal) + const terminal = this.requireTerminal(sessionId, identifier(args.id)) + let follower: TerminalFollower + const abort = () => follower.close() + follower = new TerminalFollower(() => { + signal.removeEventListener('abort', abort) + this.subscriptions.delete(follower); terminal.followers.delete(follower); terminal.holders.delete(follower) + terminal.invalidate() + if (terminal.controller === follower) { + terminal.controller = undefined; terminal.controllerId = undefined + terminal.emit({ type: 'state', info: terminal.info() }) + } + }) + // Register before awaiting the serialized snapshot, so disconnect can also + // revoke a follower whose open request has not returned yet. + this.subscriptions.add(follower) + signal.addEventListener('abort', abort, { once: true }) + if (signal.aborted) abort() + try { + if (endpoint === 'terminal/retain') { + terminal.invalidate(); terminal.holders.add(follower) + follower.push({ type: 'retained' }) + } else if (endpoint === 'terminal/follow') { + const attachmentId = identifier(args.attachmentId) + await terminal.enqueue(() => { + this.check(signal) + if (!this.subscriptions.has(follower)) throw new RpcError('TRANSPORT_CLOSED', 'The terminal attachment was disconnected.') + if (terminal.closing) throw this.scopeError('TERMINAL_NOT_FOUND', 'The terminal is closing.') + const screen = terminal.snapshot() + terminal.invalidate(); terminal.controller = follower; terminal.controllerId = attachmentId + terminal.emit({ type: 'state', info: terminal.info() }) + follower.push({ type: 'snapshot', sequence: terminal.sequence, screen, info: terminal.info() }) + terminal.followers.add(follower) + if (terminal.state !== 'running') follower.finish() + }) + } else throw new RpcError('METHOD_NOT_FOUND', 'The terminal stream does not exist.') + this.check(signal) + if (!this.subscriptions.has(follower)) throw new RpcError('TRANSPORT_CLOSED', 'The terminal attachment was disconnected.') + return follower + } catch (error) { follower.close(); throw error } + } + + /** A connection only disposes its subscriptions; the Host still owns the shells. */ + closeAll(): void { for (const subscription of [...this.subscriptions]) subscription.close() } + + private async shells(signal: AbortSignal): Promise { + try { + const result = await (this.spawn.shells?.(signal) ?? discoverTerminalShells(undefined, signal)) + this.check(signal) + if (!result.length) throw new Error() + return result + } catch (error) { + if (signal.aborted) throw error + if (error instanceof RpcError && error.code === 'TERMINAL_DISABLED') throw error + throw this.scopeError('TERMINAL_UNAVAILABLE', 'The Host terminal shells could not be discovered.') + } + } + + private async create(sessionId: string, cwd: string, args: Record, signal: AbortSignal): Promise { + const request = typeof args.request === 'object' && args.request !== null ? args.request as Record : {} + const id = identifier(request.id), key = `${sessionId}/${id}` + const existing = this.shared.terminals.get(key) + if (existing) { + if (existing.closing) throw this.scopeError('TERMINAL_NOT_FOUND', 'The terminal is closing.') + await existing.pending + this.check(signal) + if (existing.closing) throw this.scopeError('TERMINAL_NOT_FOUND', 'The terminal is closing.') + return existing.info() + } + if (this.shared.terminals.size >= MAX_TERMINALS || [...this.shared.terminals.values()].filter(item => item.sessionId === sessionId).length >= MAX_SESSION_TERMINALS) throw new RpcError('RATE_LIMITED', 'Too many remote terminals are active.') + const terminal = new OwnedTerminal(sessionId, id, cwd, + dimension(request.cols ?? 80, MAX_COLS), dimension(request.rows ?? 24, MAX_ROWS), + () => { + if (this.shared.terminals.get(key) === terminal) { + this.shared.terminals.delete(key) + this.shared.onRemoved(key) + } + }) + this.shared.terminals.set(key, terminal) + const allocationSignal = AbortSignal.any([signal, terminal.allocation.signal]) + terminal.pending = (async () => { + const shells = await this.shells(allocationSignal) + const shell = request.shellPath === undefined ? shells[0]! : shells.find(shell => shell.path === request.shellPath) + if (!shell) throw new RpcError('INVALID_MESSAGE', 'The requested shell is not available for this workspace.') + terminal.shell = shell; terminal.title = shell.name + terminal.process = await this.spawn({ argv: [shell.path, ...shell.args], cwd, + cols: terminal.cols, rows: terminal.rows, terminalType: 'xterm-256color', env: { DSH_SESSION_ID: sessionId }, signal: allocationSignal }) + this.check(allocationSignal) + void terminal.pump() + terminal.monitor() + })() + try { + await terminal.pending + // pending resolves only after allocation has been checked and committed. + // Returning failure for later request cancellation would also release + // its device claim while the committed shell is still alive. + if (terminal.closing) throw this.scopeError('TERMINAL_NOT_FOUND', 'The terminal is closing.') + return terminal.info() + } + catch (error) { + await terminal.close() + if (error instanceof RpcError || signal.aborted) throw error + throw this.scopeError('TERMINAL_UNAVAILABLE', 'The Host terminal could not be started.') + } + } + + private check(signal: AbortSignal): void { + signal.throwIfAborted() + if (!this.enabled()) throw new RpcError('TERMINAL_DISABLED', 'Remote terminal is disabled on this Host.') + } + private requireTerminal(sessionId: string, id: string): OwnedTerminal { + const terminal = this.shared.terminals.get(`${sessionId}/${id}`) + if (!terminal?.process || terminal.closing) throw this.scopeError('TERMINAL_NOT_FOUND', 'The terminal is no longer available.') + return terminal + } +} + +function identifier(value: unknown): string { + if (typeof value !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/u.test(value)) throw new RpcError('INVALID_MESSAGE', 'The terminal identifier is invalid.') + return value +} +function dimension(value: unknown, max: number): number { + if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1 || value > max) throw new RpcError('INVALID_MESSAGE', 'Terminal dimensions exceed the allowed limits.') + return value +}