import { realpath, lstat, readdir, open, stat, watch } from 'node:fs/promises' import { isAbsolute, join, relative, resolve } from 'node:path' import { RpcError } from './safe-error.js' import type { TypertRpcResult } from './typert-gateway-contract.js' import { RemoteTerminalController, RemoteTerminalState } from './remote-terminal-controller.js' import { pipeTerminalSpawner, type RemoteTerminalSpawner } from './remote-terminal-provider.js' export * from './remote-terminal-provider.js' const MAX_READ_BYTES = 4 * 1024 * 1024 export class WorkspaceBridgeState extends RemoteTerminalState {} export type WorkspaceCwdResolver = (nativeId: string, signal: AbortSignal) => Promise class AsyncQueue implements AsyncIterable { private values: T[] = [] private waiters: Array<(value: IteratorResult) => void> = [] private ended = false push(value: T): void { if (this.ended) return const waiter = this.waiters.shift() if (waiter) waiter({ done: false, value }) else this.values.push(value) } end(): void { this.ended = true while (this.waiters.length) this.waiters.shift()!({ done: true, value: undefined as never }) } next(): Promise> { const value = this.values.shift() if (value !== undefined) return Promise.resolve({ done: false, value }) if (this.ended) return Promise.resolve({ done: true, value: undefined as never }) return new Promise(resolve => this.waiters.push(resolve)) } [Symbol.asyncIterator](): AsyncIterator { return this } } /** Shared Host-owned workspace files and terminal implementation; authority comes from the backend resolver. */ export class WorkspaceBridge { private readonly terminal: RemoteTerminalController private readonly ownedSubscribers = new Set>() constructor( private readonly resolveCwd: WorkspaceCwdResolver, private readonly terminalEnabled: () => boolean, private readonly state = new WorkspaceBridgeState(), spawnTerminal: RemoteTerminalSpawner = pipeTerminalSpawner(), private readonly scope: { parse(value: unknown): { sessionId: string; nativeId: string } | undefined; domain: string; owns(value: unknown): boolean }, ) { this.terminal = new RemoteTerminalController(state, spawnTerminal, terminalEnabled, (code, message) => this.scopeError(code, message)) } isScope(value: unknown): boolean { return this.scope.parse(value) !== undefined } async call(endpoint: string, payload: unknown, signal: AbortSignal): Promise { const args = argsOf(payload) const raw = toolScope(endpoint, args) const session = this.scope.parse(raw) if (session === undefined) { if (this.scope.owns(raw)) throw this.scopeError('SESSION_INVALID', 'The CodeX session identifier is invalid.'); return undefined } if (endpoint.startsWith('workspaceFiles/')) return this.fileCall(endpoint, session.sessionId, args, signal) if (endpoint.startsWith('terminal/')) { if (!this.terminalEnabled()) throw new RpcError('TERMINAL_DISABLED', 'Remote terminal is disabled on this Host.') const revision = this.state.revision const cwd = await this.rootFor(session.sessionId, signal) if (revision !== this.state.revision) throw this.scopeError('TERMINAL_UNAVAILABLE', 'The terminal backend changed. Retry the request.') return this.terminal.call(endpoint, session.sessionId, cwd, args, signal) } return undefined } async open(endpoint: string, payload: unknown, signal: AbortSignal): Promise | undefined> { const args = argsOf(payload) const raw = toolScope(endpoint, args) const session = this.scope.parse(raw) if (session === undefined) { if (this.scope.owns(raw)) throw this.scopeError('SESSION_INVALID', 'The CodeX session identifier is invalid.'); return undefined } if (endpoint === 'workspaceFiles/changes') return this.watchChanges(session.sessionId, args, signal) if (endpoint === 'terminal/retain' || endpoint === 'terminal/follow') { if (!this.terminalEnabled()) throw new RpcError('TERMINAL_DISABLED', 'Remote terminal is disabled on this Host.') await this.rootFor(session.sessionId, signal) return this.terminal.open(endpoint, session.sessionId, args, signal) } return undefined } async closeAll(): Promise { // A transport disconnect closes subscriptions but retains Host-owned terminal // processes so a reconnect can use terminal/retain, matching Harness policy. this.terminal.closeAll() for (const queue of this.ownedSubscribers) queue.end() this.ownedSubscribers.clear() } private async fileCall(endpoint: string, sessionId: string, args: Record, signal: AbortSignal): Promise { const root = await this.rootFor(sessionId, signal) const path = typeof args.path === 'string' ? args.path : '.' signal.throwIfAborted() const target = await this.safePath(root, path, endpoint === 'workspaceFiles/list') try { if (endpoint === 'workspaceFiles/list') { const entries = await readdir(target, { withFileTypes: true }) const result = [] for (const entry of entries.slice(0, 500)) { const item = join(target, entry.name) const info = await lstat(item) if (info.isSymbolicLink()) continue result.push({ name: entry.name, type: info.isDirectory() ? 'directory' : info.isFile() ? 'file' : 'other', ...(info.isFile() ? { size: info.size } : {}) }) } return { ok: true, value: { path, entries: result, truncated: entries.length > 500 } } } const info = await stat(target) const absolutePath = target const version = `${info.mtimeMs}:${info.size}` if (endpoint === 'workspaceFiles/stat') { return { ok: true, value: { absolutePath, version, bytes: info.size } } } if (!info.isFile()) throw this.scopeError('WORKSPACE_INVALID_PATH', 'The requested workspace path is not a file.') if (info.size > MAX_READ_BYTES) throw this.scopeError('WORKSPACE_TOO_LARGE', 'The requested workspace file is too large.') const offset = readOffset(args) const limit = readLimit(args) const file = await open(target, 'r') let bytes: Buffer try { // Bound allocation even if the file grows after stat. One extra byte // detects growth instead of silently returning a truncated snapshot. const buffer = Buffer.allocUnsafe(info.size + 1) let length = 0 while (length < buffer.length) { signal.throwIfAborted() const read = await file.read(buffer, length, buffer.length - length, length) if (read.bytesRead === 0) break length += read.bytesRead } if (length > MAX_READ_BYTES) throw this.scopeError('WORKSPACE_TOO_LARGE', 'The requested workspace file is too large.') if (length !== info.size) throw this.scopeError('WORKSPACE_CHANGED', 'The workspace file changed while reading it. Retry the request.') bytes = buffer.subarray(0, length) } finally { await file.close() } if (endpoint === 'workspaceFiles/readBytes') { const slice = bytes.subarray(offset, Math.min(offset + limit, bytes.length)) return { ok: true, value: { absolutePath, version, bytes: bytes.length, offset, data: slice.toString('base64'), eof: offset + slice.length >= bytes.length, }, } } const text = bytes.toString('utf8') const slice = text.slice(offset, offset + limit) return { ok: true, value: { absolutePath: target, version: `${info.mtimeMs}:${info.size}`, text: slice, offset, lines: slice.split('\n').length, eof: offset + slice.length >= text.length } } } catch (error) { if (error instanceof RpcError) throw error throw this.scopeError('WORKSPACE_UNAVAILABLE', 'The CodeX workspace file is unavailable.') } } private async watchChanges(sessionId: string, args: Record, signal: AbortSignal): Promise> { const root = await this.rootFor(sessionId, signal) const target = await this.safePath(root, typeof args.path === 'string' ? args.path : '.', true) const queue = new AsyncQueue() signal.throwIfAborted() const watcher = watch(target, { recursive: false }) const abort = () => { watcher.return?.(); queue.end() } signal.addEventListener('abort', abort, { once: true }) void (async () => { try { for await (const event of watcher) queue.push({ kind: 'change', type: event.eventType, path: event.filename ?? '' }) } catch { /* stream close is reported by the gateway */ } finally { signal.removeEventListener('abort', abort); queue.end() } })() return queue } private scopeError(code: string, message: string): RpcError { return new RpcError(`${this.scope.domain}_${code}`, message.replaceAll('CodeX', this.scope.domain === 'CODEX' ? 'CodeX' : this.scope.domain)); } private async rootFor(sessionId: string, signal: AbortSignal): Promise { const parsed = this.scope.parse(sessionId) if (!parsed) throw this.scopeError('SESSION_INVALID', 'The CodeX session identifier is invalid.') const cwd = await this.resolveCwd(parsed.nativeId, signal) if (!cwd) throw this.scopeError('WORKSPACE_UNAVAILABLE', 'The CodeX thread has no available workspace.') try { const root = await realpath(cwd); const info = await stat(root); if (!info.isDirectory()) throw new Error(); return root } catch { throw this.scopeError('WORKSPACE_UNAVAILABLE', 'The CodeX workspace is unavailable.') } } private async safePath(root: string, path: string, directory: boolean): Promise { // Native clients may pass the displayed absolute workspace path (not only // a relative child). Accept it only when lexical and canonical containment // still prove that it belongs to this authenticated workspace root. const candidate = isAbsolute(path) ? resolve(path) : resolve(root, path) const rel = relative(root, candidate) if (rel.startsWith('..') || isAbsolute(rel)) throw this.scopeError('WORKSPACE_PATH_DENIED', 'The requested workspace path is outside the CodeX workspace.') try { const info = await lstat(candidate) if (info.isSymbolicLink()) throw new Error() const canonical = await realpath(candidate) const canonicalRel = relative(root, canonical) if (canonicalRel.startsWith('..') || isAbsolute(canonicalRel)) throw new Error() if (directory && !info.isDirectory()) throw new Error() return canonical } catch { throw this.scopeError('WORKSPACE_PATH_DENIED', 'The requested workspace path is unavailable.') } } } function argsOf(payload: unknown): Record { const value = isRecord(payload) ? payload : {}; return isRecord(value.args) ? value.args : value } function toolScope(endpoint: string, args: Record): unknown { const session = args.agentId ?? args.sessionId if (!endpoint.startsWith('terminal/')) return args.workspaceFileScopeId ?? session // Policy and process dispatch must authorize the same scope; a file scope // cannot redirect a terminal call after a different session passed policy. if ([args.agentId, args.sessionId, args.workspaceFileScopeId].some(value => value !== undefined && value !== session)) { throw new RpcError('PERMISSION_DENIED', 'The terminal scope does not match its session.') } return session } function isRecord(value: unknown): value is Record { return typeof value === 'object' && value !== null && !Array.isArray(value) } function byteOrLineRange(args: Record): Record { const options = isRecord(args.options) ? args.options : undefined if (options !== undefined && isRecord(options.range)) return options.range return isRecord(args.range) ? args.range : args } function readOffset(args: Record): number { const range = byteOrLineRange(args) return typeof range.offset === 'number' && Number.isInteger(range.offset) && range.offset >= 0 ? range.offset : 0 } function readLimit(args: Record): number { const range = byteOrLineRange(args) const value = typeof range.length === 'number' ? range.length : range.limit return typeof value === 'number' && Number.isInteger(value) && value > 0 ? Math.min(value, MAX_READ_BYTES) : MAX_READ_BYTES }