Help us shape the future of Go! Take the 2026 Go Developer Survey

term

package
v1.0.0-rc.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package term hosts terminal emulation for agent panes behind the VT interface.

Index

Constants

View Source
const ScrollbackLines = 10000

ScrollbackLines is the scrollback depth of every pane emulator.

Variables

This section is empty.

Functions

func EncodeKey

func EncodeKey(k uv.KeyPressEvent, m KeyModes) []byte

EncodeKey returns the bytes a key press sends to a guest with the given modes, or nil.

func EncodePaste

func EncodePaste(text string, bracketed bool) []byte

EncodePaste sanitises text and wraps it in bracketed-paste markers when bracketed is true.

func PaneEnv

func PaneEnv(base []string) []string

PaneEnv returns base with the terminal variables replaced by the values a pane emulator provides and the inherited pane identity removed.

Types

type Command

type Command struct {
	Argv []string
	Dir  string
	Env  []string
}

Command is a program to run on a PTY. Env is the complete child environment.

func AgentCommand

func AgentCommand(env func(string) string, dir string, argv, extraEnv []string) Command

AgentCommand runs argv in an interactive login shell, then stays in a shell when the agent exits. argv reaches the shell as separate arguments after a fixed script, so nothing in it is parsed. argv must not be empty.

func EditorCommand

func EditorCommand(env func(string) string, dir, editor string, args, extraEnv []string) Command

EditorCommand runs editor with args in an interactive login shell, then stays in a shell when the editor exits. The shell reads editor as git reads $EDITOR, so a value such as `code -w` runs code with -w; args reach the shell as separate arguments after a fixed script, so nothing in them is parsed. editor comes from the operator's own environment and must not be empty.

func EditorOnlyCommand

func EditorOnlyCommand(env func(string) string, dir, editor string, args, extraEnv []string) Command

EditorOnlyCommand is EditorCommand without the trailing shell: the command ends when the editor does.

func ShellCommand

func ShellCommand(env func(string) string, dir string, extraEnv []string) Command

ShellCommand is a login shell in dir. extraEnv is appended to the pane environment, so it wins over inherited entries.

type KeyModes

type KeyModes struct {
	KittyFlags, ModifyOtherKeys int
	AppCursor, AppKeypad        bool
}

KeyModes are the guest's keyboard modes that change how keys are encoded.

type Process

type Process struct {
	// contains filtered or unexported fields
}

Process is a child running on a pseudo terminal in its own session.

func Start

func Start(ctx context.Context, c Command, cols, rows int) (*Process, error)

Start runs c without a shell. The size is applied before the child runs.

func (*Process) Close

func (p *Process) Close() error

Close sends SIGHUP to the leader's process group and to the terminal's foreground group (a job-control shell runs its commands in their own group), waits for the child and closes the master. After a second it escalates to SIGKILL and closes the master before waiting. It is idempotent.

func (*Process) Cwd

func (p *Process) Cwd() (string, error)

Cwd is the working directory of the terminal's foreground process group, which follows a `cd` in the shell or whatever it is running.

func (*Process) Done

func (p *Process) Done() <-chan struct{}

Done is closed after the child has been waited for.

func (*Process) Foreground

func (p *Process) Foreground() (string, error)

Foreground is the name of the terminal's foreground process group leader.

func (*Process) Pid

func (p *Process) Pid() int

func (*Process) Read

func (p *Process) Read(b []byte) (int, error)

Read returns io.EOF when the child closes the terminal; EIO is the normal end of stream on Linux.

func (*Process) Resize

func (p *Process) Resize(cols, rows int) error

Resize clamps to at least 1x1 so a collapsed pane never sends a zero size.

func (*Process) Write

func (p *Process) Write(b []byte) (int, error)

type TextCell

type TextCell struct {
	Content []byte
	Width   int
}

TextCell is one history cell's text: no style, no link. Content is empty for the spacer after a wide character, and aliases history storage, so a callback must not keep it.

type VT

type VT interface {
	Write(p []byte) (int, error)
	Resize(cols, rows int)
	Size() (cols, rows int)
	CellAt(x, y int) *uv.Cell // nil outside the grid
	Cursor() (pos uv.Position, visible bool)
	ScrollbackLen() int
	// ScrollbackText calls fn with the text of history lines [from, end), oldest
	// first, until it returns false. Blank lines are skipped. It decodes no styles.
	ScrollbackText(from, end int, fn func(i int, cells []TextCell) bool)
	ScrollbackLine(i int) []uv.Cell // copy of history line i (0 oldest); nil out of range
	ScrollbackWrapped(i int) bool   // history line i soft-wraps into i+1
	HistoryTrimmed() uint64         // lines dropped from the front of the history so far: ring overwrite, CSI 3J, reflow
	RowWrapped(y int) bool          // live row y soft-wraps into y+1
	AltScreen() bool
	MouseTracking() bool                                    // guest enabled any of mouse modes 9, 1000, 1001, 1002, 1003
	SendMouse(ev uv.MouseEvent)                             // encoded per the guest's modes onto the reply stream; nothing when tracking is off
	SetClipboardHandler(fn func(selection, content string)) // guest OSC 52 writes; runs on the goroutine calling Write under the pane lock, so it must only enqueue
	SyncState() (open bool, serial uint64)                  // raw DEC 2026; serial bumps on each closed-to-open edge
	Title() string                                          // last OSC 0/2 title
	WorkingDir() string                                     // last OSC 7 path (file URL decoded to a path), "" if none
	FocusReporting() bool                                   // DECSET 1004
	KeyModes() KeyModes                                     // for EncodeKey
	BracketedPaste() bool                                   // DECSET 2004
	SetDefaultColors(fg, bg color.Color)                    // answers OSC 10 and 11 queries; mode 2031 guests get a notice on change
	SendBytes(b []byte)                                     // raw bytes queued on the reply stream, ordered with query replies
	SendKey(k uv.KeyPressEvent)                             // EncodeKey with the current KeyModes; unencodable keys send nothing
	Close() error                                           // idempotent: emulator Close, then wait for the drain
}

VT is one pane's emulator. Not safe for concurrent use; the pane serialises calls.

func NewVT

func NewVT(cols, rows int, reply io.Writer) VT

NewVT starts an emulator and a goroutine that copies its replies (query responses and SendBytes input) to reply. Close stops it.

Directories

Path Synopsis
Package rec is the timestamped PTY recording format: pane output and resizes, used to replay real sessions through the emulator.
Package rec is the timestamped PTY recording format: pane output and resizes, used to replay real sessions through the emulator.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL