Documentation
¶
Overview ¶
Package terminal drives ACP client-side terminals for command execution.
When an ACP client advertises the terminal capability, an agent can delegate shell command execution to the client so the client renders the live terminal in its UI. This package implements that delegation: foreground execution with optional timeout, a bounded pool of named background commands, and cleanup of leaked terminals when a turn is cancelled.
All operations go through the small Conn interface — the subset of the ACP agent-side connection the terminal protocol needs — so callers can supply a real *acp.AgentSideConnection or a fake in tests. A State value tracks the terminals owned by one session and is safe for concurrent use.
Index ¶
- Constants
- Variables
- type Conn
- type ExecResult
- type State
- func (s *State) BackgroundOutput(ctx context.Context, conn Conn, sessionID, commandID string) (output string, isRunning bool, exitCode *int, err error)
- func (s *State) CleanupBackground(ctx context.Context, conn Conn, sessionID string)
- func (s *State) CleanupPending(ctx context.Context, conn Conn, sessionID string)
- func (s *State) Exec(ctx context.Context, conn Conn, sessionID, toolCallID, command, cwd string, ...) (*ExecResult, error)
- func (s *State) KillBackground(ctx context.Context, conn Conn, sessionID, commandID string) (output string, exitCode *int, err error)
- func (s *State) StartBackground(ctx context.Context, conn Conn, sessionID, command, cwd, toolCallID string) (string, error)
- func (s *State) TakePending(toolCallID string) bool
- type TimeoutError
Constants ¶
const DefaultMaxBackground = 10
DefaultMaxBackground is the default maximum number of concurrent background terminals a single State permits.
const DefaultMaxBytes = 50 * 1024
DefaultMaxBytes is the output byte limit requested for each ACP terminal.
Variables ¶
var ErrAborted = errors.New("aborted")
ErrAborted is returned by State.Exec when the supplied context is cancelled before the command completes.
Functions ¶
This section is empty.
Types ¶
type Conn ¶
type Conn interface {
SessionUpdate(ctx context.Context, params acp.SessionNotification) error
CreateTerminal(ctx context.Context, params acp.CreateTerminalRequest) (acp.CreateTerminalResponse, error)
KillTerminal(ctx context.Context, params acp.KillTerminalRequest) (acp.KillTerminalResponse, error)
ReleaseTerminal(ctx context.Context, params acp.ReleaseTerminalRequest) (acp.ReleaseTerminalResponse, error)
TerminalOutput(ctx context.Context, params acp.TerminalOutputRequest) (acp.TerminalOutputResponse, error)
WaitForTerminalExit(ctx context.Context, params acp.WaitForTerminalExitRequest) (acp.WaitForTerminalExitResponse, error)
}
Conn is the subset of the ACP agent-side connection the terminal protocol uses. *acp.AgentSideConnection satisfies it.
type ExecResult ¶
type ExecResult struct {
// ExitCode is the command's exit code, or nil if the client did not
// report one.
ExitCode *int
// Output is the captured terminal output.
Output string
}
ExecResult is the outcome of a foreground command run via State.Exec.
type State ¶
type State struct {
// contains filtered or unexported fields
}
State tracks the ACP terminals owned by a single session. The zero value is not usable; construct one with NewState. State is safe for concurrent use.
func NewState ¶
func NewState() *State
NewState returns a State that permits up to DefaultMaxBackground concurrent background terminals.
func NewStateWithLimit ¶
NewStateWithLimit returns a State that permits up to limit concurrent background terminals. A limit <= 0 falls back to DefaultMaxBackground.
func (*State) BackgroundOutput ¶
func (s *State) BackgroundOutput(ctx context.Context, conn Conn, sessionID, commandID string) (output string, isRunning bool, exitCode *int, err error)
BackgroundOutput returns the current output and status of the background command identified by commandID.
func (*State) CleanupBackground ¶
CleanupBackground kills and releases all background terminals.
func (*State) CleanupPending ¶
CleanupPending kills and releases all foreground terminals still pending (not yet acknowledged by a tool-end event). This handles a session cancelled before the foreground command finished.
func (*State) Exec ¶
func (s *State) Exec(ctx context.Context, conn Conn, sessionID, toolCallID, command, cwd string, timeout int) (*ExecResult, error)
Exec runs command via the client's terminal in the foreground, embeds the terminal in the tool call identified by toolCallID, and waits for it to exit. A timeout > 0 kills the command after that many seconds and returns a *TimeoutError. If ctx is cancelled, Exec returns ErrAborted.
func (*State) KillBackground ¶
func (s *State) KillBackground(ctx context.Context, conn Conn, sessionID, commandID string) (output string, exitCode *int, err error)
KillBackground kills the background command identified by commandID and returns its final output.
func (*State) StartBackground ¶
func (s *State) StartBackground(ctx context.Context, conn Conn, sessionID, command, cwd, toolCallID string) (string, error)
StartBackground starts command as a background terminal, embeds it in the tool call identified by toolCallID, and returns its command ID. It fails once the session already has the maximum number of background terminals.
func (*State) TakePending ¶ added in v0.2.1
TakePending reports whether toolCallID has a still-pending foreground or background terminal and, if so, removes the entry. Agents use this on a tool-end event to decide whether the tool's output was already rendered by the client's terminal (so the agent can skip emitting duplicate text).
type TimeoutError ¶
type TimeoutError struct {
// Seconds is the timeout that elapsed.
Seconds int
}
TimeoutError is returned by State.Exec when a foreground command exceeds its timeout. The killed terminal's partial output is discarded.
func (*TimeoutError) Error ¶
func (e *TimeoutError) Error() string
Source Files