Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

7.4 KB
Raw Blame
import fs from 'fs'
import type { Socket } from 'net'
import type { IPty } from 'node-pty'

export const SUPPORTED_WINDOWS_CONPTY_NODE_PTY_VERSION = '1.1.0'

const SAFE_CLOSE_ERROR = 'session-host could not safely close the Windows terminal'

type PrivateConptyNative = {
  startProcess: (...args: unknown[]) => unknown
  connect: (...args: unknown[]) => unknown
  resize: (...args: unknown[]) => unknown
  clear: (...args: unknown[]) => unknown
  /** Patched node-pty 1.1.0 returns true only when it found and closed this exact HPCON. */
  kill: (ptyId: number, useConptyDll: boolean) => unknown
}

type PrivateWindowsPtyAgent = {
  constructor: { name?: unknown }
  _useConpty: boolean
  _useConptyDll: boolean
  _pty: number
  _ptyNative: PrivateConptyNative
  _inSocket: Socket
  _outSocket: Socket
  _conoutSocketWorker: {
    constructor: { name?: unknown }
    _worker: { terminate: () => unknown }
    _drainTimeout?: ReturnType<typeof setTimeout>
    _isDisposed: boolean
  }
}

type PrivateWindowsTerminal = {
  constructor: { name?: unknown }
  _pty: number
  _isReady: boolean
  _deferreds: unknown[]
  _agent: PrivateWindowsPtyAgent
  _close: () => void
}

type CloseState = {
  terminal: PrivateWindowsTerminal
  release?: Promise<void>
}

const closeStates = new WeakMap<object, CloseState>()

function fail(): never {
  // This exception can cross the session-host protocol. Keep executable paths, argv, PIDs and
  // private-property diagnostics out of it; callers may add private local logging separately.
  throw new Error(SAFE_CLOSE_ERROR)
}

function isRecord(value: unknown): value is Record<PropertyKey, unknown> {
  return typeof value === 'object' && value !== null
}

let installedNodePtyVersion: string | undefined

function nodePtyVersion(): string {
  if (installedNodePtyVersion !== undefined) return installedNodePtyVersion
  try {
    const packagePath = require.resolve('node-pty/package.json')
    const parsed = JSON.parse(fs.readFileSync(packagePath, 'utf8')) as unknown
    if (!isRecord(parsed) || typeof parsed.version !== 'string') fail()
    installedNodePtyVersion = parsed.version
    return parsed.version
  } catch {
    fail()
  }
}

function hasNativeFunction(
  native: Record<PropertyKey, unknown>,
  name: keyof PrivateConptyNative
): boolean {
  return typeof native[name] === 'function'
}

function exactWindowsConpty(proc: IPty): PrivateWindowsTerminal {
  if (process.platform !== 'win32') fail()
  if (nodePtyVersion() !== SUPPORTED_WINDOWS_CONPTY_NODE_PTY_VERSION) fail()
  if (!isRecord(proc) || proc.constructor?.name !== 'WindowsTerminal') fail()

  const agent = proc._agent
  if (!isRecord(agent) || agent.constructor?.name !== 'WindowsPtyAgent') fail()
  if (agent._useConpty !== true || typeof agent._useConptyDll !== 'boolean') fail()
  if (typeof agent._pty !== 'number' || !Number.isSafeInteger(agent._pty) || agent._pty <= 0) {
    fail()
  }
  if (
    typeof proc._pty !== 'number' ||
    !Number.isSafeInteger(proc._pty) ||
    proc._pty !== agent._pty
  ) {
    fail()
  }
  if (typeof proc._isReady !== 'boolean' || !Array.isArray(proc._deferreds)) fail()

  const native = agent._ptyNative
  if (!isRecord(native)) fail()
  if (
    !hasNativeFunction(native, 'startProcess') ||
    !hasNativeFunction(native, 'connect') ||
    !hasNativeFunction(native, 'resize') ||
    !hasNativeFunction(native, 'clear') ||
    !hasNativeFunction(native, 'kill')
  ) {
    fail()
  }
  if (
    !isRecord(agent._inSocket) ||
    typeof agent._inSocket.destroy !== 'function' ||
    typeof agent._inSocket.once !== 'function' ||
    !isRecord(agent._outSocket) ||
    typeof agent._outSocket.destroy !== 'function' ||
    typeof agent._outSocket.once !== 'function'
  ) {
    fail()
  }
  const conout = agent._conoutSocketWorker
  if (
    !isRecord(conout) ||
    conout.constructor?.name !== 'ConoutConnection' ||
    typeof conout._isDisposed !== 'boolean' ||
    !isRecord(conout._worker) ||
    typeof conout._worker.terminate !== 'function' ||
    typeof proc._close !== 'function'
  ) {
    fail()
  }
  return proc as unknown as PrivateWindowsTerminal
}

/**
 * Close one node-pty 1.1.0 Windows pseudoconsole by its native PTY id, even before the first
 * output byte. This deliberately bypasses `WindowsTerminal.kill()` (which is deferred until first
 * data) and `WindowsPtyAgent.kill()` (which starts asynchronous console-process enumeration).
 *
 * The repository's version-pinned native patch changes `conpty.kill` to return `true` only after
 * it found this exact baton and synchronously called ClosePseudoConsole for its HPCON. `undefined`
 * is the stock 1.1.0 behavior and is rejected: it cannot distinguish a close from the shell-exit
 * race that already deleted the baton. The caller must still wait for the exact recorded process
 * identities to disappear before acknowledging a destructive operation.
 */
export function closeExactWindowsConpty(proc: IPty): void {
  const terminal = exactWindowsConpty(proc)
  if (closeStates.has(terminal as unknown as object)) fail()
  const agent = terminal._agent
  let closed: unknown
  try {
    closed = agent._ptyNative.kill.call(
      agent._ptyNative,
      agent._pty,
      agent._useConptyDll
    )
  } catch {
    fail()
  }
  if (closed !== true) fail()
  closeStates.set(terminal as unknown as object, { terminal })
}

function socketClosed(socket: Socket): Promise<void> {
  if (socket.destroyed) return Promise.resolve()
  return new Promise<void>((resolve, reject) => {
    const onClose = (): void => {
      cleanup()
      resolve()
    }
    const onError = (): void => {
      cleanup()
      reject(new Error(SAFE_CLOSE_ERROR))
    }
    const cleanup = (): void => {
      socket.removeListener('close', onClose)
      socket.removeListener('error', onError)
    }
    socket.once('close', onClose)
    socket.once('error', onError)
    try {
      socket.destroy()
    } catch {
      cleanup()
      reject(new Error(SAFE_CLOSE_ERROR))
    }
  })
}

function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
  return isRecord(value) && typeof value.then === 'function'
}

/**
 * Finish the exact ConPTY's private transport teardown after the caller has independently proven
 * the shell process tree absent. The output socket is destroyed last because its `close` event is
 * node-pty's public `onExit`; by then the input handle and the exact ConoutConnection worker are
 * already gone, so a host cannot acknowledge through `onExit` while those resources remain live.
 */
export function releaseExactWindowsConpty(proc: IPty): Promise<void> {
  const state = closeStates.get(proc as unknown as object)
  if (!state || state.terminal !== (proc as unknown as PrivateWindowsTerminal)) {
    return Promise.reject(new Error(SAFE_CLOSE_ERROR))
  }
  if (state.release) return state.release

  state.release = (async () => {
    const terminal = state.terminal
    const agent = terminal._agent
    const conout = agent._conoutSocketWorker
    try {
      terminal._close()
      await socketClosed(agent._inSocket)

      if (conout._drainTimeout !== undefined) {
        clearTimeout(conout._drainTimeout)
        conout._drainTimeout = undefined
      }
      conout._isDisposed = true
      const terminated = conout._worker.terminate()
      if (!isPromiseLike(terminated)) fail()
      await terminated

      // This is the public exit-event commit point. Keep it after every awaited private cleanup.
      await socketClosed(agent._outSocket)
    } catch {
      fail()
    }
  })()
  return state.release
}