session

package
v0.8.19 Latest Latest
Warning

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

 Go to latest Published: Oct 9, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package session owns PTY-backed process lifecycles and exposes neutral, typed events. It deliberately has no dependency on Bubble Tea.

Index

Constants

View Source 
const StopBudget = gracefulStopTimeout + 2*forcedStopTimeout + descendantGraceTime + finalOutputDrainTime + time.Second

StopBudget is the longest one Stop can take: the grace period, then the forced kill and its confirmation, and the descendants' cleanup and output drain. A caller that gives a stop less reports one still under way as unconfirmed, and the agent is then locked as stop_uncertain: when the Windows grace became five seconds, the web gateway's five-second budget did that to every agent the console close never reaches. Budgets for a Stop, a Restart or a shutdown are built on it. It bounds a PTY stop; a tmux stop is a few tmux commands, each bounded by the tmux backend's own command timeout, so a wedged tmux server can outlast it and have its stop reported unconfirmed.

Variables

View Source 
var (
	ErrClosed = errors.New("PTY session closed")
	// ErrStopUncertain means Relayer requested termination but could not confirm
	// that the command leader was reaped and that no member of its PTY process
	// group can still run; on Linux a member left as a zombie does not count. A
	// caller must not start a replacement process while this error is present.
	ErrStopUncertain = errors.New("PTY session stop not confirmed")
)

ErrClosed is returned when an operation targets a PTY that has already been closed or a manager that no longer accepts sessions.

Functions

This section is empty.

Types

type AdapterEvent 

type AdapterEvent struct {
	Event adapters.Event
}

AdapterEvent carries the single backend-neutral semantic representation produced by an adapter or by a real session lifecycle transition.

type AdapterEventWithdrawn added in v0.3.0 

type AdapterEventWithdrawn struct {
	Event adapters.Event
}

AdapterEventWithdrawn reports that the agent took its question back off the screen before anyone decided on it.

It is neither a decision nor a failure: nobody answered, and there is nothing left to answer. Whatever is showing the occurrence to the operator has to stop showing it, or an operator keeps looking at a card whose question is gone from the agent's terminal.

type Error 

type Error struct {
	SessionID string
	Err       error
}

Error reports an unexpected error while reading the PTY.

type Event 

type Event interface {
	// contains filtered or unexported methods
}

Event is emitted by Manager for asynchronous session state changes. The unexported marker keeps the event set closed while allowing consumers to use type switches over the exported concrete types.

type Exited 

type Exited struct {
	SessionID string
	Err       error
}

Exited is retained for source compatibility. Managers now publish a real AdapterEvent with type process_exit instead of emitting this legacy value.

type Info 

type Info = terminal.Info

Info remains an alias for compatibility with the original PTY API while every backend now shares terminal.Info.

type Manager 

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

Manager is the sole owner of process lifecycles and PTY descriptors.

func NewManager 

func NewManager(
	parent context.Context,
	events chan<- Event,
	patterns []intercept.Pattern,
	ringCapacity int,
) (*Manager, error)

NewManager validates every prompt pattern before any process can start.

func NewManagerWithRegistry 

func NewManagerWithRegistry(
	parent context.Context,
	events chan<- Event,
	registry *adapters.Registry,
	ringCapacity int,
) (*Manager, error)

NewManagerWithRegistry creates a PTY owner around the application adapter registry. The registry is validated before any process can start and creates independent adapter state for every session.

func (*Manager) AnsiOutput 

func (m *Manager) AnsiOutput(sessionID string) (string, error)

func (*Manager) BeginShutdown 

func (m *Manager) BeginShutdown()

BeginShutdown immediately unblocks essential event senders. Close performs descriptor/process cleanup and joins every owned goroutine.

func (*Manager) Close 

func (m *Manager) Close()

func (*Manager) Context 

func (m *Manager) Context() context.Context

func (*Manager) Done 

func (m *Manager) Done(sessionID string) (<-chan struct{}, error)

Done exposes lifecycle completion without leaking the underlying process or PTY descriptor. The channel is closed before the corresponding process_exit AdapterEvent is emitted.

func (*Manager) Name 

func (m *Manager) Name() string

Name identifies the concrete backend without exposing PTY implementation details to the application or TUI.

func (*Manager) Output 

func (m *Manager) Output(sessionID string) (string, error)

func (*Manager) PendingEvent 

func (m *Manager) PendingEvent(sessionID string) (*adapters.Event, error)

PendingEvent returns an independent copy of the actionable occurrence still awaiting a decision, if any.

func (*Manager) Remove added in v0.4.0 

func (m *Manager) Remove(sessionID string) error

Remove releases the identity of one fully terminated session so a later Start can reuse it. It refuses while the process might still be alive: session.done only closes after Wait has reaped the process, so an open channel means the previous process may still run and a replacement could never share the identity safely.

func (*Manager) Resize 

func (m *Manager) Resize(sessionID string, columns, rows int) error

func (*Manager) Result 

func (m *Manager) Result(sessionID string) (exited bool, waitErr error, exitCode *int, err error)

Result returns a stable lifecycle snapshot once Wait has completed.

func (*Manager) Revision 

func (m *Manager) Revision(sessionID string) (uint64, error)

Revision is the latest semantic event occurrence sequence for the session.

func (*Manager) SendData 

func (m *Manager) SendData(sessionID string, data []byte) error

SendData is the compatibility path for callers that do not yet retain the actionable event ID. It still uses Processor.Resolve so acknowledgement only happens after the exact bytes have been delivered successfully.

func (*Manager) SendDataForEvent 

func (m *Manager) SendDataForEvent(sessionID, eventID string, data []byte) error

SendDataForEvent atomically validates the pending occurrence, delivers the exact bytes and acknowledges only after a successful write.

func (*Manager) SendInput 

func (m *Manager) SendInput(sessionID string, value string) error

func (*Manager) SendLine 

func (m *Manager) SendLine(ctx context.Context, sessionID, line string) error

SendLine is the ordinary-input path. Processor.SendLine atomically confirms that the process is live and no actionable event is pending, then appends exactly one carriage return without acknowledging semantic state.

func (*Manager) SendRaw added in v0.6.0 

func (m *Manager) SendRaw(ctx context.Context, sessionID string, data []byte) error

SendRaw writes raw terminal input bytes directly to the session PTY device. Used for interactive terminal streaming (keystrokes, VT escape sequences, Ctrl+C). The write ends with ctx where the device takes a deadline, the Unix master: an agent that reads nothing blocked it in the kernel for good.

func (*Manager) SetRecorder added in v0.7.0 

func (m *Manager) SetRecorder(recorder terminal.Recorder)

SetRecorder attaches a transcript recorder. It must be called before Start; sessions already running keep the recorder they were created with, because a transcript that begins mid-session would carry a misleading header size and a first offset the replay cannot explain.

func (*Manager) Start 

func (m *Manager) Start(spec agent.Spec, columns, rows int) (Info, error)

Start validates and launches one direct or explicitly requested shell command with a correctly sized PTY.

func (*Manager) Stop 

func (m *Manager) Stop(sessionID string) error

Stop terminates one owned session without affecting its siblings.

type OutputAvailable 

type OutputAvailable struct {
	SessionID string
}

OutputAvailable invalidates a consumer's cached output snapshot. The latest bounded snapshot is retrieved with Manager.Output.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.