Documentation
¶
Index ¶
- Constants
- Variables
- func TerminalEnvDefaults() map[string]string
- type Client
- type ClientManager
- type ConfigDirManager
- type EventSourceConfig
- type ManagerOption
- type Session
- func (s *Session) Attach(clientID string) *Client
- func (s *Session) ClientCount() int
- func (s *Session) CreatedAt() time.Time
- func (s *Session) Detach(clientID string)
- func (s *Session) ExitNotify() <-chan struct{}
- func (s *Session) IsPaused() bool
- func (s *Session) IsRunning() bool
- func (s *Session) Monitor() *monitor.AgentMonitor
- func (s *Session) Pause() error
- func (s *Session) Resize(rows, cols int)
- func (s *Session) Resume() error
- func (s *Session) Start(ctx context.Context) error
- func (s *Session) StartEventSources(cfg EventSourceConfig) (*SessionEventSources, error)
- func (s *Session) Stop()
- func (s *Session) SubscribeTerminal(subscriberID string) *TerminalSubscription
- func (s *Session) TerminalSubscriberCount() int
- func (s *Session) UnsubscribeTerminal(subscriberID string)
- func (s *Session) Wait()
- func (s *Session) WritePTY(data []byte) (int, error)
- type SessionConfig
- type SessionEventSources
- type SessionInfo
- type SessionManager
- func (sm *SessionManager) Count() int
- func (sm *SessionManager) Create(id string, cfg SessionConfig) (*Session, error)
- func (sm *SessionManager) Get(id string) (*Session, error)
- func (sm *SessionManager) Kill(id string) error
- func (sm *SessionManager) List() []SessionInfo
- func (sm *SessionManager) Shutdown(timeout time.Duration) error
- type StreamTerminalRequest
- type TerminalAttached
- type TerminalClientMessage
- type TerminalDetached
- type TerminalInput
- type TerminalOutput
- type TerminalResize
- type TerminalServerMessage
- type TerminalSubscription
- type VirtualTerminal
- func (vt *VirtualTerminal) AppendScrollback(data []byte)
- func (vt *VirtualTerminal) Close() error
- func (vt *VirtualTerminal) KillChild()
- func (vt *VirtualTerminal) PipeOutput(onData func([]byte)) error
- func (vt *VirtualTerminal) Resize(rows, cols, childRows int)
- func (vt *VirtualTerminal) ScrollbackSnapshot() []byte
- func (vt *VirtualTerminal) SendSignal(sig syscall.Signal) error
- func (vt *VirtualTerminal) StartPTY(command string, args []string, rows, cols int, env map[string]string, ...) error
- func (vt *VirtualTerminal) WritePTY(p []byte, timeout time.Duration) (int, error)
Constants ¶
const ( DefaultTERM = "xterm-256color" DefaultCOLORTERM = "truecolor" DefaultCOLORFGBG = "15;0" // white on black (dark theme) )
const ( // SubscriptionBufferSize is the number of output chunks buffered per subscriber. // At ~4KB per chunk, this allows ~256KB of buffered output before drops. SubscriptionBufferSize = 64 // MaxScrollbackSnapshotBytes caps the scrollback snapshot sent to subscribers. // At 4MB, this fits within ConnectRPC's default 16MB message limit while // providing substantial history (~40K lines of typical terminal output). MaxScrollbackSnapshotBytes = 4 * 1024 * 1024 )
const InputBurstBytes = 64 * 1024
InputBurstBytes is the burst allowance for input (paste operations).
const MaxInputRateBytes = 10 * 1024
MaxInputRateBytes is the maximum sustained input rate in bytes per second.
const MaxTerminalChunkSize = 64 * 1024
MaxTerminalChunkSize is the maximum size of a single TerminalOutput message. Larger PTY reads are split into multiple messages.
Variables ¶
var ErrPTYWriteTimeout = errors.New("pty write timed out (child may be hung)")
ErrPTYWriteTimeout is returned when a write to the PTY master times out, indicating the child process is likely hung.
Functions ¶
func TerminalEnvDefaults ¶
TerminalEnvDefaults returns the environment variables to set for headless child processes. These are merged with (but overridden by) any driver-specific or user-specified env vars.
Types ¶
type Client ¶
type Client struct {
ID string
// contains filtered or unexported fields
}
Client represents a connected client that can receive PTY output from a session.
func (*Client) Close ¶
func (c *Client) Close()
Close marks the client as closed and closes the output channel.
type ClientManager ¶
type ClientManager struct {
// contains filtered or unexported fields
}
ClientManager handles multi-client attach/detach for a session.
func NewClientManager ¶
func NewClientManager() *ClientManager
NewClientManager creates a new client manager.
func (*ClientManager) Attach ¶
func (cm *ClientManager) Attach(id string) *Client
Attach adds a client and returns it. If a client with the same ID already exists, the old one is closed and replaced.
func (*ClientManager) CloseAll ¶
func (cm *ClientManager) CloseAll()
CloseAll closes and removes all clients.
func (*ClientManager) Count ¶
func (cm *ClientManager) Count() int
Count returns the number of attached clients.
func (*ClientManager) Detach ¶
func (cm *ClientManager) Detach(id string)
Detach removes and closes a client by ID.
func (*ClientManager) FanOut ¶
func (cm *ClientManager) FanOut(data []byte)
FanOut sends data to all attached clients. Non-blocking per client.
func (*ClientManager) List ¶
func (cm *ClientManager) List() []string
List returns the IDs of all attached clients.
type ConfigDirManager ¶
type ConfigDirManager struct {
BaseDir string
}
ConfigDirManager manages per-session config directories for 3rd party agent drivers. Config directories contain authentication tokens, settings, and injected files (like CLAUDE.md) that drivers need at launch time.
func NewConfigDirManager ¶
func NewConfigDirManager(baseDir string) *ConfigDirManager
NewConfigDirManager creates a new config directory manager.
func (*ConfigDirManager) Cleanup ¶
func (m *ConfigDirManager) Cleanup(sessionID string) error
Cleanup removes the config directory for a session.
func (*ConfigDirManager) EnsureDir ¶
func (m *ConfigDirManager) EnsureDir(sessionID string) (string, error)
EnsureDir creates the config directory if it doesn't exist and returns the path.
func (*ConfigDirManager) InjectFile ¶
func (m *ConfigDirManager) InjectFile(sessionID, relativePath string, data []byte) error
InjectFile writes a file into the session's config directory. This is used by orchestrators to inject CLAUDE.md, agents.md, MCP configs, etc.
func (*ConfigDirManager) StablePath ¶
func (m *ConfigDirManager) StablePath(sessionID string) string
StablePath returns the deterministic config directory path for a session. The same session ID always resolves to the same path, which is critical for auth token persistence across pause/resume cycles.
type EventSourceConfig ¶
type EventSourceConfig struct {
// OTEL callbacks — set by the driver's event handler
OtelCallbacks otelserver.Callbacks
// Session log path and callback — set by the driver
SessionLogPath string
OnSessionLogLine func(line []byte)
// Hook event handler — set by the driver
OnHookEvent func(eventName string, payload []byte) []monitor.AgentEvent
}
EventSourceConfig configures the event sources for a session.
type ManagerOption ¶
type ManagerOption func(*SessionManager)
ManagerOption configures the SessionManager.
func WithMaxSessions ¶
func WithMaxSessions(n int) ManagerOption
WithMaxSessions sets the maximum number of concurrent sessions.
type Session ¶
type Session struct {
ID string
Config SessionConfig
VT *VirtualTerminal
// contains filtered or unexported fields
}
Session represents a terminal multiplexer session with a PTY, an agent driver, and multi-client support.
func NewSession ¶
func NewSession(id string, cfg SessionConfig) *Session
NewSession creates a new session but does not start it.
func (*Session) ClientCount ¶
ClientCount returns the number of attached clients.
func (*Session) ExitNotify ¶
func (s *Session) ExitNotify() <-chan struct{}
ExitNotify returns a channel that is closed when the session exits.
func (*Session) Monitor ¶
func (s *Session) Monitor() *monitor.AgentMonitor
Monitor returns the session's agent monitor.
func (*Session) Pause ¶
Pause marks the session as paused. This is a controller-level gate that prevents new interactions while paused. The PTY child process continues running — pause/resume operates at the interaction level, not the process level.
func (*Session) StartEventSources ¶
func (s *Session) StartEventSources(cfg EventSourceConfig) (*SessionEventSources, error)
StartEventSources initializes and starts the event sources for a session. The OTEL server must be started before launching the child process so that its endpoint can be injected into the child's environment.
func (*Session) SubscribeTerminal ¶
func (s *Session) SubscribeTerminal(subscriberID string) *TerminalSubscription
SubscribeTerminal creates a new terminal output subscription. The subscriber receives a scrollback snapshot of recent output and then live raw PTY output chunks via the Chunks channel.
func (*Session) TerminalSubscriberCount ¶
TerminalSubscriberCount returns the number of active terminal subscribers.
func (*Session) UnsubscribeTerminal ¶
UnsubscribeTerminal removes a terminal output subscription.
type SessionConfig ¶
type SessionConfig struct {
DriverType string
Command string
Args []string
CWD string
Env map[string]string
InitialRows int
InitialCols int
}
SessionConfig configures a new session.
type SessionEventSources ¶
type SessionEventSources struct {
OtelServer *otelserver.Server
SessionTailer *sessionlog.Tailer
// contains filtered or unexported fields
}
SessionEventSources holds the running event sources for a session.
func (*SessionEventSources) OtelEndpoint ¶
func (ses *SessionEventSources) OtelEndpoint() string
OtelEndpoint returns the OTEL server endpoint URL for injection into the child process environment.
func (*SessionEventSources) Stop ¶
func (ses *SessionEventSources) Stop()
Stop shuts down all event sources.
type SessionInfo ¶
type SessionInfo struct {
ID string
DriverType string
Command string
State monitor.State
SubState monitor.SubState
CreatedAt time.Time
ClientCount int
}
SessionInfo is a summary of a session's state for listing.
type SessionManager ¶
type SessionManager struct {
// contains filtered or unexported fields
}
SessionManager manages the lifecycle of terminal multiplexer sessions.
func NewSessionManager ¶
func NewSessionManager(opts ...ManagerOption) *SessionManager
NewSessionManager creates a new session manager.
func (*SessionManager) Count ¶
func (sm *SessionManager) Count() int
Count returns the number of sessions.
func (*SessionManager) Create ¶
func (sm *SessionManager) Create(id string, cfg SessionConfig) (*Session, error)
Create creates a new session with the given configuration. The session is not started until Start is called on it.
func (*SessionManager) Get ¶
func (sm *SessionManager) Get(id string) (*Session, error)
Get retrieves a session by ID.
func (*SessionManager) Kill ¶
func (sm *SessionManager) Kill(id string) error
Kill stops and removes a session.
func (*SessionManager) List ¶
func (sm *SessionManager) List() []SessionInfo
List returns info about all sessions, sorted by creation time.
type StreamTerminalRequest ¶
type StreamTerminalRequest struct {
SessionID string `json:"session_id"`
}
StreamTerminalRequest is the initial attach request from the client.
type TerminalAttached ¶
type TerminalAttached struct {
Rows int `json:"rows"`
Cols int `json:"cols"`
Scrollback []byte `json:"scrollback,omitempty"`
}
TerminalAttached is sent after successful subscription, including current dimensions and scrollback history for replay.
type TerminalClientMessage ¶
type TerminalClientMessage struct {
Attach *StreamTerminalRequest `json:"attach,omitempty"`
Input *TerminalInput `json:"input,omitempty"`
Resize *TerminalResize `json:"resize,omitempty"`
}
TerminalClientMessage is a message from the client to the server.
type TerminalDetached ¶
type TerminalDetached struct {
Reason string `json:"reason"` // "session_ended", "kicked", "error"
}
TerminalDetached is sent when the session ends or the client is kicked.
type TerminalInput ¶
type TerminalInput struct {
Data []byte `json:"data"`
}
TerminalInput carries raw keystrokes from the client to the PTY.
type TerminalOutput ¶
type TerminalOutput struct {
Data []byte `json:"data"`
}
TerminalOutput carries raw PTY output (including ANSI sequences) to the client.
type TerminalResize ¶
TerminalResize carries terminal dimension changes from the client.
type TerminalServerMessage ¶
type TerminalServerMessage struct {
Attached *TerminalAttached `json:"attached,omitempty"`
Output *TerminalOutput `json:"output,omitempty"`
Detached *TerminalDetached `json:"detached,omitempty"`
}
TerminalServerMessage is a message from the server to the client.
type TerminalSubscription ¶
type TerminalSubscription struct {
ID string
Chunks chan []byte // Buffered channel acts as bounded queue
Done chan struct{} // Closed when subscription is cancelled
// Scrollback snapshot delivered on subscribe
Scrollback []byte
Rows, Cols int
}
TerminalSubscription is a per-subscriber output stream with bounded buffering. Each subscriber gets its own ring buffer of raw PTY output chunks. Slow consumers drop oldest chunks rather than blocking the output pipeline.
type VirtualTerminal ¶
type VirtualTerminal struct {
Ptm *os.File // PTY master
Cmd *exec.Cmd
Mu sync.Mutex // Guards all terminal state and writes
Rows, Cols int
ChildRows int
// Child process state
ChildExited bool
ChildHung bool
ExitError error
// contains filtered or unexported fields
}
VirtualTerminal wraps a PTY and child process with robust lifecycle management.
func NewVirtualTerminal ¶
func NewVirtualTerminal() *VirtualTerminal
NewVirtualTerminal creates a VirtualTerminal with scrollback support.
func (*VirtualTerminal) AppendScrollback ¶
func (vt *VirtualTerminal) AppendScrollback(data []byte)
AppendScrollback adds raw PTY output to the scrollback buffer. This is called from PipeOutput's callback to record output for late-attaching terminal subscribers.
func (*VirtualTerminal) Close ¶
func (vt *VirtualTerminal) Close() error
Close closes the PTY master file descriptor.
func (*VirtualTerminal) KillChild ¶
func (vt *VirtualTerminal) KillChild()
KillChild sends SIGKILL to the child process.
func (*VirtualTerminal) PipeOutput ¶
func (vt *VirtualTerminal) PipeOutput(onData func([]byte)) error
PipeOutput reads from the PTY master and calls onData for each chunk. This blocks until the child exits or the PTY is closed. Runs its own goroutine to wait on the child process.
func (*VirtualTerminal) Resize ¶
func (vt *VirtualTerminal) Resize(rows, cols, childRows int)
Resize changes the PTY window size.
func (*VirtualTerminal) ScrollbackSnapshot ¶
func (vt *VirtualTerminal) ScrollbackSnapshot() []byte
ScrollbackSnapshot returns a copy of the most recent scrollback history as raw bytes suitable for replay into xterm.js. The snapshot is capped at MaxScrollbackSnapshotBytes. Must be called with Mu held.
func (*VirtualTerminal) SendSignal ¶
func (vt *VirtualTerminal) SendSignal(sig syscall.Signal) error
SendSignal sends a signal to the child process.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package driver defines the TermmuxDriverAdapter interface and canonical conversation types for bidirectional session log conversion.
|
Package driver defines the TermmuxDriverAdapter interface and canonical conversation types for bidirectional session log conversion. |
|
claudecode
Package claudecode implements the TermmuxDriverAdapter for Claude Code CLI.
|
Package claudecode implements the TermmuxDriverAdapter for Claude Code CLI. |
|
codex
Package codex implements the TermmuxDriverAdapter for the Codex CLI.
|
Package codex implements the TermmuxDriverAdapter for the Codex CLI. |
|
eventsrc
|
|
|
eventstore
Package eventstore provides JSONL event persistence.
|
Package eventstore provides JSONL event persistence. |
|
otelserver
Package otelserver provides a per-session HTTP server that receives OTEL log, metric, and trace data from agent CLIs.
|
Package otelserver provides a per-session HTTP server that receives OTEL log, metric, and trace data from agent CLIs. |
|
sessionlog
Package sessionlog provides a JSONL file tailer that polls for new lines.
|
Package sessionlog provides a JSONL file tailer that polls for new lines. |
|
Package monitor provides the agent state machine, metrics, and event fan-out.
|
Package monitor provides the agent state machine, metrics, and event fan-out. |