agentbackend

type Backend interface {
	InstanceBackend
	PoolBackend
	UtilizationReader
}

type DeleteResult struct {
	Complete bool
}

type DesiredInstance struct {
	Ref      InstanceRef
	Pool     PoolRef
	Revision string

	Name        string
	Description string
	Harness     Harness
	Image       string
	Source      Source
	Model       Model
	Env         map[string]string
	Files       []File
	Secrets     []SecretRef

	// Requests is what this sandbox is guaranteed, and Limits is what it may
	// burst to. Both are derived from the pool rather than declared by the
	// agent: a pool is a shared bucket, and an agent has no inherent size.
	//
	// They are carried here, rather than computed by a backend, so that they
	// participate in the desired revision. Resizing a pool therefore changes
	// every sandbox's revision and restarts it, which is the only way a running
	// sandbox picks up new limits.
	Requests InstanceResources
	Limits   InstanceResources

	// Port is the HTTP port the agent serves on. Zero means it serves nothing,
	// and a backend should publish no address for it.
	Port int
	// Terminal asks the backend to keep the sandbox attachable for an
	// interactive session.
	Terminal bool
}

type DesiredPool struct {
	Ref      PoolRef
	Revision string
	Capacity ResourceQuantity
	// MaxSandboxes bounds how many sandboxes share the pool, and so determines
	// each one's guaranteed share.
	MaxSandboxes int
	Suspended    bool
}

type Disabled struct{}

type Event struct {
	Kind     ResourceKind
	Instance InstanceRef
	Pool     PoolRef
}

type File struct {
	Path    string
	Content []byte
	Mode    uint32
}

type Harness struct {
	ID string
	// Interactive asks the backend to allocate a TTY and keep stdin open, the
	// equivalent of `docker run -it`. Without it an image whose entrypoint is a
	// shell exits as soon as it starts.
	Interactive bool
}

type InstanceBackend interface {
	ReconcileInstance(context.Context, DesiredInstance) (InstanceObservation, error)
	ObserveInstance(context.Context, InstanceRef) (InstanceObservation, error)
	DeleteInstance(context.Context, InstanceRef) (DeleteResult, error)
}

type InstanceObservation struct {
	Ref               InstanceRef
	Exists            bool
	ObservedRevision  string
	State             State
	URL               string
	Reason            string
	Message           string
	BackendGeneration int64
}

type InstanceRef struct {
	ID        string
	Namespace string
	UserID    string
	BackendID string
}

type InstanceResources struct {
	CPUVCPUs    float64
	MemoryBytes int64
}

type InstanceUtilization struct {
	Ref         InstanceRef
	State       State
	Utilization ResourceUtilization
}

type Model struct {
	ID       string
	Endpoint string
}

type PoolBackend interface {
	ReconcilePool(context.Context, DesiredPool) (PoolObservation, error)
	ObservePool(context.Context, PoolRef) (PoolObservation, error)
	DeletePool(context.Context, PoolRef) (DeleteResult, error)
}

type PoolObservation struct {
	Ref               PoolRef
	Exists            bool
	ObservedRevision  string
	State             State
	Schedulable       bool
	Capacity          ResourceQuantity
	Reason            string
	Message           string
	BackendGeneration int64
}

type PoolRef struct {
	ID        string
	BackendID string
}

type Pressure struct {
	CPU     bool
	Memory  bool
	Storage bool
}

type ResourceKind string

type ResourceQuantity struct {
	CPUVCPUs     float64
	MemoryBytes  int64
	StorageBytes int64
}

type ResourceUtilization struct {
	CPUVCPUs     float64
	MemoryBytes  int64
	StorageBytes int64
}

type SecretRef struct {
	ID       string
	EnvName  string
	FilePath string

	// Version changes whenever the value behind ID changes. It participates in
	// the desired revision so that a rotated secret restarts the sandbox.
	//
	// Agents read their credentials once at startup and cannot reload them, so
	// a sandbox left running across a rotation would hold a credential that no
	// longer works. Versioning the reference propagates the rotation while
	// keeping the value itself out of desired state, status and the revision.
	Version string

	// Value is the secret itself, passed transiently so a backend can write it
	// wherever that backend keeps secrets. It is excluded from the desired
	// revision by DesiredInstance.Redacted, and must never be persisted to
	// instance spec or status, or logged.
	Value string
}

type Source struct {
	URL      string
	Revision string
	Subdir   string
}

type State string

type Subscriber interface {
	Subscribe(context.Context, func(context.Context, Event) error) error
}

type TerminalBackend interface {
	// AttachTerminal connects to a sandbox's existing console. It attaches to
	// the process the sandbox is already running rather than starting a new
	// one, so an operator sees the same session the agent is driving.
	//
	// This requires the sandbox to have been started with a TTY, which is what
	// a harness marks by being interactive. Attaching to one that was not is an
	// error rather than a silently empty session.
	AttachTerminal(ctx context.Context, ref InstanceRef, size TerminalSize) (TerminalSession, error)
}

type TerminalSession interface {
	io.ReadWriteCloser

	// Resize tells the sandbox its terminal changed shape. Without it a program
	// drawing a full-screen interface keeps using the size it saw at startup.
	Resize(size TerminalSize) error
}

type TerminalSize struct {
	Rows uint16
	Cols uint16
}

type UtilizationReader interface {
	GetPoolUtilization(context.Context, PoolRef) (UtilizationSnapshot, error)
}

type UtilizationSnapshot struct {
	Timestamp time.Time
	Pool      ResourceUtilization
	Instances []InstanceUtilization
	Pressure  Pressure
	// StorageMeasured reports whether Pool.StorageBytes is a real measurement.
	// A backend that cannot attribute disk usage to this pool alone leaves it
	// false, so a caller can say so rather than draw an empty disk that is
	// really an unknown one.
	StorageMeasured bool
}