cli

type Backend ¶

type Backend interface {
	Spawner
	Parser
}

Backend is the minimum interface a CLI backend must implement. Optional capabilities (Resumer, Streamer, InputFormatter) are discovered via type assertion at runtime.

Backends must implement at least one send path for Engine.Start to succeed: either Streamer+InputFormatter or Resumer. Start returns agentrun.ErrSendNotSupported if neither is available.

type Engine ¶

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

Engine is a CLI subprocess engine that adapts a Backend into an agentrun.Engine. It orchestrates subprocess lifecycle, message pumping, and graceful shutdown.

func NewEngine(backend Backend, opts ...EngineOption) *Engine

func (e *Engine) Start(_ context.Context, session agentrun.Session, opts ...agentrun.Option) (agentrun.Process, error)

func (e *Engine) Validate() (retErr error)

type EngineOption ¶

type EngineOption func(*EngineOptions)

EngineOption configures an Engine at construction time.

func WithGracePeriod(d time.Duration) EngineOption

func WithOutputBuffer(size int) EngineOption

func WithScannerBuffer(size int) EngineOption

type EngineOptions ¶

type EngineOptions struct {
	// OutputBuffer is the channel buffer size for process output messages.
	OutputBuffer int

	// ScannerBuffer is the maximum line size in bytes for the stdout scanner.
	ScannerBuffer int

	// GracePeriod is the duration to wait after SIGTERM before sending SIGKILL.
	GracePeriod time.Duration
}

EngineOptions holds resolved construction-time configuration for a CLI engine. Use NewEngine with EngineOption functions to customize these values.

type InputFormatter ¶

type InputFormatter interface {
	FormatInput(message string) ([]byte, error)
}

InputFormatter encodes user messages for delivery to a subprocess stdin pipe. InputFormatter is optional — the CLIEngine discovers it via type assertion independently of Streamer:

if f, ok := backend.(InputFormatter); ok {
    data, err := f.FormatInput("user message")
}

A backend can implement Streamer, InputFormatter, both, or neither. message must be valid UTF-8. Implementations must return an error for messages containing null bytes.

type Parser ¶

type Parser interface {
	ParseLine(line string) (agentrun.Message, error)
}

Parser converts a raw stdout line into a structured Message. Every CLI backend must implement Parser.

ParseLine returns ErrSkipLine when a line should be consumed but produces no Message. Any other non-nil error indicates a parse failure. A returned Message with zero Timestamp will have its Timestamp set by the CLIEngine.

type Resumer ¶

type Resumer interface {
	ResumeArgs(session agentrun.Session, initialPrompt string) (binary string, args []string, err error)
}

Resumer builds the exec.Cmd arguments to resume an existing session. Resumer is optional — the CLIEngine discovers it via type assertion:

if r, ok := backend.(Resumer); ok {
    binary, args, err := r.ResumeArgs(session, "continue from here")
}

The initialPrompt parameter is baked into the subprocess args because some CLI tools (e.g., Claude Code's --resume flag) require the first message at spawn time (single-shot resume pattern).

type Spawner ¶

type Spawner interface {
	SpawnArgs(session agentrun.Session) (binary string, args []string)
}

Spawner builds the exec.Cmd arguments to start a new session. Every CLI backend must implement Spawner.

SpawnArgs is a pure argument builder — it must not fail. Backends that need to validate session state should do so in their constructor or in Engine.Validate. Implementations MUST return arguments suitable for exec.Cmd (pre-split argv) and MUST NOT pass arguments through a shell interpreter.

type Streamer ¶

type Streamer interface {
	StreamArgs(session agentrun.Session) (binary string, args []string)
}

Streamer builds a long-lived streaming command that attaches to a subprocess for continuous output. When a backend implements Streamer, the initial prompt is NOT included in the command args — the caller must send it explicitly via Process.Send after Start returns. Streamer is optional — the CLIEngine discovers it via type assertion:

if s, ok := backend.(Streamer); ok {
    binary, args := s.StreamArgs(session)
}