TerminalHandle

Handle for controlling and monitoring terminals created via createTerminal

Overview

Handle for controlling and monitoring a terminal created via createTerminal.

Provides methods to:

• Get current output without waiting
• Wait for command completion
• Kill the running command
• Release terminal resources

Important: Always call release() when done with the terminal to free resources.

The terminal supports async disposal via Symbol.asyncDispose for automatic cleanup. You can use await using to ensure the terminal is automatically released when it goes out of scope.

Constructor

constructor(
  public id: string,
  sessionId: string,
  conn: Connection
)

Creates a new terminal handle. This is typically not called directly - use AgentSideConnection.createTerminal() instead.

id · string · required

The terminal ID

sessionId · string · required

The session ID this terminal belongs to

conn · Connection · required

The underlying connection object

Properties

id

id: string

The unique identifier for this terminal. This ID can be used in ToolCallContent with type “terminal” to embed the terminal in tool calls.

Methods

currentOutput

async currentOutput(): Promise<TerminalOutputResponse>

Gets the current terminal output without waiting for the command to exit.

Returns immediately with the current state of the terminal, including any output generated so far. If the command has already exited, the exit status will be included.

response · TerminalOutputResponse

The current terminal output and exit status (if available)

waitForExit

async waitForExit(): Promise<WaitForTerminalExitResponse>

Waits for the terminal command to complete and returns its exit status.

This method blocks until the command finishes execution and provides the final exit code or signal information.

response · WaitForTerminalExitResponse

The exit status of the terminal command

kill

async kill(): Promise<KillTerminalResponse>

Kills the terminal command without releasing the terminal.

The terminal remains valid after killing, allowing you to:

• Get the final output with currentOutput()
• Check the exit status
• Release the terminal when done

Useful for implementing timeouts or cancellation.

response · KillTerminalResponse

An empty object on success

release

async release(): Promise<ReleaseTerminalResponse | void>

Releases the terminal and frees all associated resources.

If the command is still running, it will be killed. After release, the terminal ID becomes invalid and cannot be used with other terminal methods.

Tool calls that already reference this terminal will continue to display its output.

Important: Always call this method when done with the terminal.

response · ReleaseTerminalResponse | void

An empty object on success

[Symbol.asyncDispose]

async [Symbol.asyncDispose](): Promise<void>

Async disposal method for automatic resource cleanup.

This allows the terminal to be used with await using syntax for automatic cleanup:

// Terminal is automatically released when it goes out of scope
await using terminal = await connection.createTerminal({
  sessionId: 'session-123',
  command: 'npm test'
});

const output = await terminal.currentOutput();
// terminal.release() is called automatically at the end of the block

Promise<void> · Promise<void>

A promise that resolves when the terminal has been released