Documentation
¶
Overview ¶
Package supervisor owns the lifecycle of one controller's session workers.
It is the only place a worker is created, so the agent space policy cannot be bypassed, no worker runs without a durable generation row, and no worker is accepted without the credential this controller issued for that exact generation.
Index ¶
- type EnsureRequest
- type Options
- type Supervisor
- func (s *Supervisor) AcceptWorker(ctx context.Context, hello protocol.Hello) (protocol.HelloAck, error)
- func (s *Supervisor) AgentSpaces() *worker.AgentSpaceSet
- func (s *Supervisor) Current(sessionID uuid.UUID) (*protocol.Worker, bool)
- func (s *Supervisor) Ensure(ctx context.Context, request EnsureRequest) (*protocol.Worker, error)
- func (s *Supervisor) EnsureSessionWorker(ctx context.Context, sessionID uuid.UUID, workspace string, ...) (*protocol.Worker, error)
- func (s *Supervisor) Stop(ctx context.Context, sessionID uuid.UUID) error
- func (s *Supervisor) StopAll(ctx context.Context) error
- func (s *Supervisor) WorkerConnected(sessionID, generationID uuid.UUID)
- func (s *Supervisor) WorkerDisconnected(ctx context.Context, sessionID, generationID uuid.UUID)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type EnsureRequest ¶
type EnsureRequest struct {
SessionID uuid.UUID
Workspace string
AgentSpaceName string
// contains filtered or unexported fields
}
EnsureRequest asks for one session's live worker.
type Options ¶
type Options struct {
Store *session.Store
Workflows *db.WorkflowStorage
AgentSpaces *worker.AgentSpaceSet
// Metrics counts worker lifecycles and takes each worker's reports. Nil
// disables both.
Metrics *metrics.Metrics
// Launchers holds one launcher per kind. A kind with no launcher cannot
// run: a Docker agent space on a controller with no Docker socket is
// refused rather than run somewhere else.
Launchers map[worker.Kind]worker.Launcher
// SocketRoot is the controller's private worker socket directory. It is
// separate from the SQLite directory and from the public API.
SocketRoot string
// ConfigDirectory is the global Peen configuration every worker reads.
ConfigDirectory string
// WritableConfigDirectory mounts ConfigDirectory writable into Docker
// workers instead of read-only.
WritableConfigDirectory bool
// LearnedDirectory is the global learned directory a Docker worker
// mounts, or empty when auto-evolve is off. WritableLearnedDirectory
// mounts it writable instead of read-only.
LearnedDirectory string
WritableLearnedDirectory bool
// SystemAgent allows a system session's worker to start. StateDirectory
// is the path its instructions name.
SystemAgent bool
StateDirectory string
ReadyTimeout time.Duration
StopTimeout time.Duration
// ResumeAfterCrash lets work a worker left unfinished when its connection
// died continue in the next worker. False, the default, pauses it until a
// turn resumes it.
ResumeAfterCrash bool
}
Options builds a supervisor.
type Supervisor ¶
type Supervisor struct {
// contains filtered or unexported fields
}
Supervisor holds one live worker per session.
func New ¶
func New(options Options) (*Supervisor, error)
New validates the supervisor's dependencies.
func (*Supervisor) AcceptWorker ¶
func (s *Supervisor) AcceptWorker( ctx context.Context, hello protocol.Hello, ) (protocol.HelloAck, error)
AcceptWorker verifies one registration against the durable generation.
A worker is accepted only when this controller recorded that session, that generation, and that credential hash, and the generation has not already ended. It is what stops a worker replaying another generation's credential.
func (*Supervisor) AgentSpaces ¶ added in v0.19.0
func (s *Supervisor) AgentSpaces() *worker.AgentSpaceSet
AgentSpaces exposes the deployment's allowed agent spaces for reporting.
func (*Supervisor) Ensure ¶
func (s *Supervisor) Ensure( ctx context.Context, request EnsureRequest, ) (*protocol.Worker, error)
Ensure returns the session's registered worker, launching one when the session has none.
A session keeps its worker across turns. A worker whose connection ended is replaced by a new generation rather than reused, and the replacement is recorded before it runs.
func (*Supervisor) EnsureSessionWorker ¶
func (s *Supervisor) EnsureSessionWorker( ctx context.Context, sessionID uuid.UUID, workspace string, agentSpaceName string, ) (*protocol.Worker, error)
EnsureSessionWorker is Ensure in the shape the control surface routes with.
The workspace and agent space come from the stored session, so a client naming a session cannot also choose where it runs or what it may do.
func (*Supervisor) Stop ¶
Stop ends one session's worker and records the transition. Stopping a session that has none is not an error.
func (*Supervisor) StopAll ¶
func (s *Supervisor) StopAll(ctx context.Context) error
StopAll ends every supervised worker, reporting the first failure while still stopping the rest.
func (*Supervisor) WorkerConnected ¶ added in v0.14.2
func (s *Supervisor) WorkerConnected(sessionID, generationID uuid.UUID)
WorkerConnected releases the launch that is waiting for this generation. The listener calls it only after the worker is installed, so the launch always finds the connection it was released for.
func (*Supervisor) WorkerDisconnected ¶ added in v0.24.0
func (s *Supervisor) WorkerDisconnected( ctx context.Context, sessionID, generationID uuid.UUID, )
WorkerDisconnected settles only the generation whose socket ended. Lifecycle admission prevents its socket cleanup deleting a replacement.