host

README

Agent Runtime host

host owns the process lifecycle around one managed Agent Runtime. It starts the HTTP server, establishes and observes an optional registration lease, and performs bounded graceful shutdown and deregistration.

It does not load deployment configuration, construct registry providers, validate Router credentials, or implement Agent behavior. Callers must provide those dependencies explicitly before creating the host.

runtimeHost, err := host.New(host.Config{
	Address:         listenAddress,
	Handler:         managedA2AHandler,
	Registration:    registration,
	ShutdownTimeout: 5 * time.Second,
	Signals:         []os.Signal{os.Interrupt, syscall.SIGTERM},
})
if err != nil {
	return err
}
return runtimeHost.Run(context.Background())

Host errors expose one lifecycle Stage and preserve the underlying typed error for errors.Is and errors.As. Their default message contains only the stage and a static safe description; it never copies a provider response, credential, request payload, or arbitrary cause text.

if stage, ok := host.StageOf(err); ok {
	logger.Error("Runtime stopped", "stage", stage)
}

There is no retry, alternate endpoint, stale lease, or shutdown-timeout fallback. A caller that wants any such policy must own and document it outside this package.

Documentation

Overview

Package host provides the lifecycle boundary for a managed Agent Runtime.

It owns bootstrap-stage error context, HTTP serving, registration lease observation, and graceful shutdown. It does not own an Agent's model, prompt, tool, workflow, memory, or Session implementation.

Index

• func Wrap(stage Stage, message string, err error) error
• type Config
• type Error
  • func (e *Error) Error() string
  • func (e *Error) Stage() Stage
  • func (e *Error) Unwrap() error
• type Host
  • func New(config Config) (*Host, error)
  • func (host *Host) Run(ctx context.Context) error
• type Registration
• type Server
• type ServerFactory
• type Stage
  • func StageOf(err error) (Stage, bool)

Functions

func Wrap

func Wrap(stage Stage, message string, err error) error

Wrap creates a staged host error. message must be a static, provider-safe description chosen by the host integration; it must not contain secrets, request payloads, or raw dependency responses.

Types

type Config

type Config struct {
	Address         string
	Handler         http.Handler
	Registration    Registration
	ShutdownTimeout time.Duration
	Signals         []os.Signal
	NewServer       ServerFactory
}

Config contains only explicit host policy. Address, handler, timeout, and signal behavior are required. An empty Signals slice explicitly disables process-signal handling, which is useful when the caller owns cancellation.

type Error

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

Error adds a stable lifecycle stage without exposing the wrapped error's message by default. The wrapped error remains available to errors.Is/As so callers can make an explicit local diagnostic decision.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Stage

func (e *Error) Stage() Stage

Stage returns the host lifecycle stage associated with err.

func (*Error) Unwrap

func (e *Error) Unwrap() error

type Host

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

Host owns one Runtime process lifecycle.

func New

func New(config Config) (*Host, error)

New validates explicit host policy and returns a lifecycle runner.

func (*Host) Run

func (host *Host) Run(ctx context.Context) error

Run starts the HTTP server, observes registration, and performs graceful shutdown. A context cancellation is a normal lifecycle completion; server, lease, and shutdown failures remain staged errors.

type Registration

type Registration interface {
	Register(context.Context) error
	Run(context.Context) error
	Deregister(context.Context) error
}

Registration is the minimal lifecycle contract needed by a managed Agent host. Implementations own the provider-specific registration protocol.

type Server

type Server interface {
	ListenAndServe() error
	Shutdown(context.Context) error
}

Server is implemented by *http.Server and can be replaced with a fake in tests.

type ServerFactory

type ServerFactory func(address string, handler http.Handler) Server

ServerFactory allows tests and embedders to provide a server implementation. The default factory creates an *http.Server from Address and Handler.

type Stage

type Stage string

Stage identifies a lifecycle boundary owned by the Runtime host.

const (
	StageConfig       Stage = "config"
	StageRegistration Stage = "registration"
	StageHandler      Stage = "handler"
	StageServe        Stage = "serve"
	StageShutdown     Stage = "shutdown"
)

func StageOf

func StageOf(err error) (Stage, bool)

StageOf extracts the first staged host error from an error chain.