runner

package
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: Jan 24, 2026 License: AGPL-3.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// DefaultMaxInputSize is 4KB (conservative default)
	DefaultMaxInputSize = 4096
	// EnvMaxInputSize is the environment variable to override the default
	EnvMaxInputSize = "TRELLIS_MAX_INPUT_SIZE"
)
View Source 
var (
	ErrInputTooLarge = errors.New("input exceeds maximum allowed size")
	ErrInvalidUTF8   = errors.New("input contains invalid UTF-8 sequences")
)

Functions

func SanitizeInput added in v0.5.2 

func SanitizeInput(input string) (string, error)

SanitizeInput cleans user input by enforcing size limits, validating UTF-8, and stripping dangerous control characters.

Types

type ContentRenderer 

type ContentRenderer func(string) (string, error)

ContentRenderer is a function that transforms the content before outputting it. This allows for TUI rendering (markdown to ANSI) without coupling the core package.

type IOHandler 

type IOHandler interface {
	// Output presents the actions to the user.
	// Returns true if the output requires user input (e.g. asking a question),
	// or if the handler expects to read input after this.
	Output(ctx context.Context, actions []domain.ActionRequest) (bool, error)

	// Input reads a response from the user.
	Input(ctx context.Context) (string, error)

	// HandleTool executes a side-effect requested by the engine.
	// In a text/CLI context, this might just log the request or ask for confirmation.
	HandleTool(ctx context.Context, call domain.ToolCall) (domain.ToolResult, error)

	// SystemOutput presents a meta-message to the user (e.g. system logs, status updates).
	// This is distinct from content rendering.
	SystemOutput(ctx context.Context, msg string) error
}

IOHandler defines the strategy for interacting with the user. This allows switching between Text (CLI/TUI) and JSON (Structured) modes.

type JSONHandler 

type JSONHandler struct {
	Writer   io.Writer
	Encoder  *json.Encoder
	Registry *registry.Registry
	// contains filtered or unexported fields
}

JSONHandler implements the IOHandler interface for structured JSON-Lines communication.

func NewJSONHandler 

func NewJSONHandler(r io.Reader, w io.Writer, opts ...JSONHandlerOption) *JSONHandler

NewJSONHandler creates a handler for JSON IO. It starts a background goroutine to read from r.

func (*JSONHandler) HandleTool added in v0.4.0 

func (h *JSONHandler) HandleTool(ctx context.Context, call domain.ToolCall) (domain.ToolResult, error)

HandleTool for JSONHandler emits the tool call as JSON.

func (*JSONHandler) Input 

func (h *JSONHandler) Input(ctx context.Context) (string, error)

func (*JSONHandler) Output 

func (h *JSONHandler) Output(ctx context.Context, actions []domain.ActionRequest) (bool, error)

func (*JSONHandler) SystemOutput added in v0.5.0 

func (h *JSONHandler) SystemOutput(ctx context.Context, msg string) error

type JSONHandlerOption added in v0.6.0 

type JSONHandlerOption func(*JSONHandler)

JSONHandlerOption defines configuration for JSONHandler.

func WithJSONHandlerRegistry added in v0.6.0 

func WithJSONHandlerRegistry(reg *registry.Registry) JSONHandlerOption

WithJSONHandlerRegistry configures the tool registry.

type Option added in v0.6.0 

type Option func(*Runner)

Option defines a functional option for configuring the Runner.

func WithHeadless added in v0.6.0 

func WithHeadless(headless bool) Option

WithHeadless sets the runner to headless mode.

func WithInputHandler added in v0.6.0 

func WithInputHandler(handler IOHandler) Option

WithInputHandler configures a custom IOHandler.

func WithInterceptor added in v0.6.0 

func WithInterceptor(interceptor ToolInterceptor) Option

WithInterceptor configures the tool execution middleware.

func WithLogger added in v0.6.0 

func WithLogger(logger *slog.Logger) Option

WithLogger configures the structured logger.

func WithRenderer added in v0.6.0 

func WithRenderer(renderer ContentRenderer) Option

WithRenderer configures the content renderer (e.g. TUI, Markdown).

func WithSessionID added in v0.6.0 

func WithSessionID(id string) Option

WithSessionID sets the session ID for persistence context. This is required if WithStore is used.

func WithStore added in v0.6.0 

func WithStore(store ports.StateStore) Option

WithStore configures the StateStore for persistence.

func WithToolRunner added in v0.7.0 

func WithToolRunner(tr ToolRunner) Option

WithToolRunner configures the strategy for executing side-effects.

type Runner 

type Runner struct {
	Handler     IOHandler
	Store       ports.StateStore
	Logger      *slog.Logger
	Headless    bool
	SessionID   string
	Renderer    ContentRenderer
	Interceptor ToolInterceptor
	ToolRunner  ToolRunner
}

Runner handles the execution loop of the Trellis engine using provided IO. This allows for easy testing and integration with different frontends (CLI, TUI, etc). Runner handler the execution loop of the Trellis engine.

func NewRunner 

func NewRunner(opts ...Option) *Runner

NewRunner creates a new Runner with options.

func (*Runner) Run 

func (r *Runner) Run(ctx context.Context, engine *trellis.Engine, initialState *domain.State) (*domain.State, error)

Run executes the engine loop until termination.

type SessionManager added in v0.6.0 

type SessionManager struct {
	Store ports.StateStore
}

SessionManager handles the lifecycle of a durable session. It coordinates between the Runner, the Engine, and the StateStore.

func NewSessionManager added in v0.6.0 

func NewSessionManager(store ports.StateStore) *SessionManager

NewSessionManager creates a new SessionManager.

func (*SessionManager) LoadOrStart added in v0.6.0 

func (sm *SessionManager) LoadOrStart(
	ctx context.Context,
	engine *trellis.Engine,
	sessionID string,
	initialContext map[string]any,
) (*domain.State, bool, error)

LoadOrStart attempts to load an existing session. If not found, it starts a new one. Returns the state and a boolean indicating if it was loaded (true) or new (false).

func (*SessionManager) Save added in v0.6.0 

func (sm *SessionManager) Save(ctx context.Context, sessionID string, state *domain.State) error

Save persists the state.

type SignalManager added in v0.5.2 

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

SignalManager handles the complexity of OS signals, context cancellation, and platform-specific race conditions (e.g. Windows Stdin EOF vs Interrupt).

func NewSignalManager added in v0.5.2 

func NewSignalManager() *SignalManager

NewSignalManager creates a new manager and immediately starts listening for signals.

func (*SignalManager) CheckRace added in v0.5.2 

func (sm *SignalManager) CheckRace()

CheckRace waits briefly to see if a context cancellation follows an error. This is specifically to mitigate a race condition on Windows/PowerShell where Ctrl+C causes an EOF or Input Error slightly before the signal context is cancelled.

func (*SignalManager) Context added in v0.5.2 

func (sm *SignalManager) Context() context.Context

Context returns the current signal context.

func (*SignalManager) Reset added in v0.5.2 

func (sm *SignalManager) Reset()

Reset re-arms the signal listener. Should be called after a signal has been successfully handled/intercepted to allow capturing subsequent signals.

func (*SignalManager) Stop added in v0.5.2 

func (sm *SignalManager) Stop()

Stop permanently stops the signal listener.

type TextHandler 

type TextHandler struct {
	Reader   *bufio.Reader
	Writer   io.Writer
	Renderer ContentRenderer
	Registry *registry.Registry
	// contains filtered or unexported fields
}

TextHandler implements the standard text-based interface.

func NewTextHandler 

func NewTextHandler(r io.Reader, w io.Writer, opts ...TextHandlerOption) *TextHandler

NewTextHandler creates a handler for standard text IO.

func (*TextHandler) HandleTool added in v0.4.0 

func (h *TextHandler) HandleTool(ctx context.Context, call domain.ToolCall) (domain.ToolResult, error)

HandleTool for TextHandler mocks the execution by printing to stdout.

func (*TextHandler) Input 

func (h *TextHandler) Input(ctx context.Context) (string, error)

func (*TextHandler) Output 

func (h *TextHandler) Output(ctx context.Context, actions []domain.ActionRequest) (bool, error)

func (*TextHandler) SystemOutput added in v0.5.0 

func (h *TextHandler) SystemOutput(ctx context.Context, msg string) error

type TextHandlerOption added in v0.6.0 

type TextHandlerOption func(*TextHandler)

TextHandlerOption defines configuration for TextHandler.

func WithTextHandlerRegistry added in v0.6.0 

func WithTextHandlerRegistry(reg *registry.Registry) TextHandlerOption

WithTextHandlerRegistry configures the tool registry.

func WithTextHandlerRenderer added in v0.6.0 

func WithTextHandlerRenderer(renderer ContentRenderer) TextHandlerOption

WithTextHandlerRenderer configures the content renderer.

type ToolInterceptor added in v0.5.0 

type ToolInterceptor func(ctx context.Context, call domain.ToolCall) (bool, domain.ToolResult, error)

ToolInterceptor is a middleware that can intercept, modify, or block a tool call. It returns true if execution should proceed, or false to block it. If blocked, it should return a ToolResult describing the denial (typically an error).

func AutoApproveMiddleware added in v0.5.0 

func AutoApproveMiddleware() ToolInterceptor

AutoApproveMiddleware allows everything.

func ConfirmationMiddleware added in v0.5.0 

func ConfirmationMiddleware(handler IOHandler) ToolInterceptor

ConfirmationMiddleware prompts the user via the provided Handler before allowing execution. It is "aware" of the IOHandler to use its Input/Output methods, but keeps the policy logic separate.

Note: This leverages the IOHandler.SystemOutput capability to send meta-messages. This allows the prompt ("Allow execution?") to be distinct from the flow content.

func MultiInterceptor added in v0.5.0 

func MultiInterceptor(interceptors ...ToolInterceptor) ToolInterceptor

MultiInterceptor chains multiple interceptors.

type ToolRunner added in v0.7.0 

type ToolRunner interface {
	Execute(ctx context.Context, call domain.ToolCall) (domain.ToolResult, error)
}

ToolRunner defines the strategy for executing side-effects. It decouples execution logic (Process, HTTP, MCP) from IO logic (Text, JSON).

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.