PtyHandle

PTY session handle for managing a single PTY session.

Properties:

• sessionId string

Provides methods for sending input, resizing the terminal, waiting for completion, and managing the WebSocket connection to a PTY session.

Example:

// Create a PTY session
const ptyHandle = await process.createPty({
  id: 'my-session',
  cols: 120,
  rows: 30,
  onData: (data) => {
    const text = new TextDecoder().decode(data);
    process.stdout.write(text);
  },
});

// Send commands
await ptyHandle.sendInput('ls -la\n');
await ptyHandle.sendInput('exit\n');

// Wait for completion
const result = await ptyHandle.wait();
console.log(`PTY exited with code: ${result.exitCode}`);

// Clean up
await ptyHandle.disconnect();

Accessors

error

Get Signature

get error(): string

Error message if the PTY failed

Returns:

• string

exitCode

Get Signature

get exitCode(): number

Exit code of the PTY process (if terminated)

Returns:

• number

Constructors

new PtyHandle()

new PtyHandle(
   ws: WebSocket,
   handleResize: (cols: number, rows: number) => Promise<PtySessionInfo>,
   handleKill: () => Promise<void>,
   onPty: (data: Uint8Array) => void | Promise<void>,
   sessionId: string): PtyHandle

Parameters:

• ws WebSocket
• handleResize (cols: number, rows: number) => Promise<PtySessionInfo>
• handleKill () => Promise<void>
• onPty (data: Uint8Array) => void | Promise<void>
• sessionId string

Returns:

• PtyHandle

Methods

disconnect()

disconnect(): Promise<void>

Disconnect from the PTY session and clean up resources.

Closes the WebSocket connection and releases any associated resources. Should be called when done with the PTY session.

Returns:

• Promise<void>

Example:

// Always clean up when done
try {
  // ... use PTY session
} finally {
  await ptyHandle.disconnect();
}

isConnected()

isConnected(): boolean

Check if connected to the PTY session

Returns:

• boolean

kill()

kill(): Promise<void>

Kill the PTY process and terminate the session.

Forcefully terminates the PTY session and its associated process. This operation is irreversible and will cause the PTY to exit immediately.

Returns:

• Promise<void>

Throws:

If the kill operation fails

Example:

// Kill a long-running process
await ptyHandle.kill();

// Wait to confirm termination
const result = await ptyHandle.wait();
console.log(`Process terminated with exit code: ${result.exitCode}`);

resize()

resize(cols: number, rows: number): Promise<PtySessionInfo>

Resize the PTY terminal dimensions.

Changes the terminal size which will notify terminal applications about the new dimensions via SIGWINCH signal.

Parameters:

• cols number - New number of terminal columns
• rows number - New number of terminal rows

Returns:

• Promise<PtySessionInfo>

Example:

// Resize to 120x30
await ptyHandle.resize(120, 30);

sendInput()

sendInput(data: string | Uint8Array<ArrayBufferLike>): Promise<void>

Send input data to the PTY session.

Sends keyboard input or commands to the terminal session. The data will be processed as if it was typed in the terminal.

Parameters:

• data Input data to send (commands, keystrokes, etc.) - string | Uint8Array<ArrayBufferLike>

Returns:

• Promise<void>

Throws:

If PTY is not connected or sending fails

Example:

// Send a command
await ptyHandle.sendInput('ls -la\n');

// Send raw bytes
await ptyHandle.sendInput(new Uint8Array([3])); // Ctrl+C

wait()

wait(): Promise<PtyResult>

Wait for the PTY process to exit and return the result.

This method blocks until the PTY process terminates and returns information about how it exited.

Returns:

• Promise<PtyResult> - Result containing exit code and error information

Example:

// Wait for process to complete
const result = await ptyHandle.wait();

if (result.exitCode === 0) {
  console.log('Process completed successfully');
} else {
  console.log(`Process failed with code: ${result.exitCode}`);
  if (result.error) {
    console.log(`Error: ${result.error}`);
  }
}

waitForConnection()

waitForConnection(): Promise<void>

Wait for the WebSocket connection to be established.

This method ensures the PTY session is ready to receive input and send output. It waits for the server to confirm the connection is established.

Returns:

• Promise<void>

Throws:

If connection times out (10 seconds) or connection fails