supervisor

package
v0.43.1 Latest Latest
Warning

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

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 11 Imported by: 0

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

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
}

EnsureRequest asks for one session's live worker.

type Options

type Options struct {
	Store       *session.Store
	Workflows   *db.WorkflowStorage
	AgentSpaces *worker.AgentSpaceSet

	// 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

	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) Current

func (s *Supervisor) Current(sessionID uuid.UUID) (*protocol.Worker, bool)

Current reports a session's live worker without launching one.

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

func (s *Supervisor) Stop(ctx context.Context, sessionID uuid.UUID) error

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL