control

package
v0.13.0 Latest Latest
Warning

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

Go to latest
Published: Sep 24, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Overview

Package control owns the control surface's workspace policy and session registry. It decides which host directories a client may open as a session and resolves each request to the one canonical path that identifies it.

Index

Constants

View Source
const (
	// CoreServiceName opens configuration, SQLite, the provider registry, the
	// workspace policy, and the agent runtime.
	CoreServiceName = "control-core"

	// APIServiceName serves REST, the global WebSocket feed, and metrics over
	// what CoreServiceName opened.
	APIServiceName = "control-api"
)

Service names for the two control services. They live here rather than in either service because the dependency edge between them needs the other's name, and a service never imports a sibling service.

Variables

This section is empty.

Functions

func DialableAddress

func DialableAddress(listenAddress string) string

DialableAddress turns a configured listen address into one a client can connect to. A listener bound to every interface is written without a host, and that form cannot be dialed as written.

Types

type Core

type Core struct {
	Config    peenconfig.Config
	Upstreams []peenconfig.Upstream
	Runtime   *agent.Runtime
	Store     *session.Store
	Handle    *db.Handle
	Sessions  *Registry

	// Profiles are the deployment's allowed execution profiles. The API reads
	// them so a client can see what it may name.
	Profiles *worker.ProfileSet

	// Workers supervises this controller's session workers. Shutdown stops
	// them through it, so no worker outlives the controller that launched it.
	Workers *supervisor.Supervisor

	// Turns routes an accepted client message to its session's worker. The
	// control plane routes work; it does not run the model loop.
	Turns *TurnRouter

	// Events carries durable worker events to the live feed. control-core
	// creates it and control-api registers the delivery path, so a record is
	// written before any client can see it.
	Events *EventRelay

	Metrics *metrics.Metrics
}

Core is the durable state and runtime that control-core opens and control-api serves. One controller owns exactly one Core.

type EventRelay

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

EventRelay carries worker events from the durable write to the live feed.

It exists because the two halves come up in order: control-core opens the store and the worker socket, and control-api brings up the WebSocket hub afterwards. The relay is created with the first and its sink registered by the second, so neither service has to import the other.

Events reach it only after the controller has written them, so a client can never see an event the database does not already hold. Before a sink is registered, publishing is a no-op rather than an error: a worker's durable write must not fail because nothing is listening yet.

func NewEventRelay

func NewEventRelay() *EventRelay

NewEventRelay builds an unattached relay.

func (*EventRelay) PublishSessionEvents

func (r *EventRelay) PublishSessionEvents(
	ctx context.Context,
	sessionID uuid.UUID,
	events []session.EventInput,
)

PublishSessionEvents delivers events that are already durable.

func (*EventRelay) SetSink

func (r *EventRelay) SetSink(sink EventSink)

SetSink registers the live delivery path. Registering twice replaces it, which is what a restarted API service needs.

type EventSink

type EventSink func(
	ctx context.Context,
	sessionID uuid.UUID,
	events []session.EventInput,
)

EventSink delivers one session's durable events to live clients.

type Handoff

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

Handoff passes one Core from the service that opens it to the service that serves it.

Servicepack builds each service from a no-argument factory, so two services in one process cannot receive a shared dependency through a constructor. The dependency graph orders them, control-api after control-core, and the readiness gate makes the Core present before control-api runs. Await still blocks rather than trusting that order, so a misconfigured graph surfaces as a timeout instead of a nil dereference.

func NewHandoff

func NewHandoff() *Handoff

NewHandoff builds an empty handoff. Tests use one of these instead of the process-wide handoff so scenarios stay independent.

func SharedHandoff

func SharedHandoff() *Handoff

SharedHandoff returns the process-wide handoff between the control services.

func (*Handoff) Await

func (h *Handoff) Await(ctx context.Context) (*Core, error)

Await returns the published Core, blocking until control-core publishes one or the context ends.

func (*Handoff) Clear

func (h *Handoff) Clear()

Clear drops the published Core so the next controller in this process starts from nothing. control-core clears it as it shuts down, and tests clear it between scenarios.

func (*Handoff) Publish

func (h *Handoff) Publish(core *Core) error

Publish records the Core and releases every waiter. Publishing twice is a wiring bug, because one process runs one controller.

type OpenResult

type OpenResult struct {
	Session *models.Session
	Created bool
}

OpenResult reports the session a workspace resolved to and whether this call is what created it.

type Registry

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

Registry is the control surface's session registry. It is the only place a client-requested workspace becomes a durable session, so the workspace policy cannot be bypassed by reaching the store directly.

func NewRegistry

func NewRegistry(options RegistryOptions) (*Registry, error)

NewRegistry validates the registry's dependencies.

func (*Registry) ExecutionProfiles

func (r *Registry) ExecutionProfiles() api.ExecutionProfileList

ExecutionProfiles reports the profiles a client may name, with the capability warning for any that grants host-root-equivalent access.

func (*Registry) ListProfileDecisions

func (r *Registry) ListProfileDecisions(
	ctx context.Context,
	sessionID uuid.UUID,
	params api.ListSessionProfileDecisionsParams,
) (api.SessionProfileDecisionPage, error)

ListProfileDecisions returns one page of a session's profile decision history, newest first.

func (*Registry) ListSessions

func (r *Registry) ListSessions(
	ctx context.Context,
	params api.ListSessionsParams,
) (api.SessionPage, error)

ListSessions returns one bounded page of the sessions this control surface holds, newest-updated first.

func (*Registry) ListWorkerGenerations

func (r *Registry) ListWorkerGenerations(
	ctx context.Context,
	sessionID uuid.UUID,
	params api.ListSessionWorkersParams,
) (api.WorkerGenerationPage, error)

ListWorkerGenerations returns one page of a session's worker generations, newest first.

func (*Registry) Open

func (r *Registry) Open(
	ctx context.Context,
	requested string,
	profileName string,
) (OpenResult, error)

Open resolves a requested workspace and returns the one durable session for it, creating that session the first time the directory is opened.

The policy check runs before the store is touched, so a path outside every configured root is refused without creating a row. Opening the same directory again, by any of its names, resumes the existing session rather than making a second one.

func (*Registry) OpenWorkspaceSession

func (r *Registry) OpenWorkspaceSession(
	ctx context.Context,
	workspace string,
	profileName string,
) (api.OpenedSession, error)

OpenWorkspaceSession resolves a requested workspace to its durable session and reports whether this call created it.

It returns commerr.ErrPermissionDenied when the path falls outside every configured workspace root or names an execution profile the deployment does not define, and commerr.ErrValidationFailed when the path is not a usable directory. None of those cases creates a session.

func (*Registry) ReconfigureSession

func (r *Registry) ReconfigureSession(
	ctx context.Context,
	sessionID uuid.UUID,
	request api.ReconfigureSessionRequest,
) (api.SessionProfileDecision, error)

ReconfigureSession moves an idle session to a different execution profile.

The profile must be one the operator defined, the session must have no turn in flight, and the change is recorded with the caller's reason. The session's current worker is stopped, so the next turn starts a new generation under the new profile rather than continuing in the old environment.

func (*Registry) Roots

func (r *Registry) Roots() []string

Roots reports the directories this registry will open sessions under.

func (*Registry) WorkspaceRoots added in v0.13.0

func (r *Registry) WorkspaceRoots() api.WorkspaceRootList

WorkspaceRoots reports the directories this authenticated controller lets a client select when opening its first workspace session.

type RegistryOptions

type RegistryOptions struct {
	Store        *session.Store
	Policy       *WorkspacePolicy
	RootAgent    string
	DefaultModel string

	// Profiles are the deployment's allowed execution profiles. A client names
	// one when it opens a workspace, and an undefined name is refused.
	Profiles *worker.ProfileSet

	// Workers supervises each session's worker process. Reconfiguring a
	// session stops its worker so the next turn starts a new generation under
	// the new profile. A nil supervisor records the decision without replacing
	// anything.
	Workers *supervisor.Supervisor
}

RegistryOptions supplies the durable store and the policy a registry opens workspaces under.

type TurnRouter

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

TurnRouter sends one accepted client message to its session's worker.

This is the join between the public control surface and the private worker protocol. The controller resolves which session the message is for and which operator-selected profile that session runs under, makes sure a worker for that profile is live, then hands the turn over. The controller never runs the model loop itself.

func NewTurnRouter

func NewTurnRouter(
	registry *Registry,
	workers WorkerSupervisor,
) (*TurnRouter, error)

NewTurnRouter binds the session registry to the worker supervisor.

func (*TurnRouter) CancelSessionTurn

func (r *TurnRouter) CancelSessionTurn(
	ctx context.Context,
	sessionID uuid.UUID,
) (bool, error)

CancelSessionTurn asks the session's live worker to cancel its active turn.

A session with no live worker has nothing running in this controller, so the answer is that nothing was cancelled rather than an error.

func (*TurnRouter) RunSessionMessage

func (r *TurnRouter) RunSessionMessage(
	ctx context.Context,
	sessionID uuid.UUID,
	request agent.MessageRequest,
	requestID uuid.UUID,
) (*agent.MessageRunResult, error)

RunSessionMessage runs one turn in the session's worker.

The session is loaded first, so a message naming a session that does not exist fails before any worker is started. The profile comes from the stored session rather than the request: naming a profile is an operator decision recorded at open or reconfigure time, never something a message carries.

func (*TurnRouter) SignalSessionJob

func (r *TurnRouter) SignalSessionJob(
	ctx context.Context,
	sessionID uuid.UUID,
	jobID uuid.UUID,
	signal string,
) (*api.JobSignalResponse, error)

SignalSessionJob asks the session's live worker to signal one of its jobs.

A job's process group is a child of the worker, so the controller cannot reach it. A nil response means no live worker holds the job, which tells the caller to record the request against the durable row instead of treating it as an error.

type WorkerSupervisor

type WorkerSupervisor interface {
	EnsureSessionWorker(
		ctx context.Context,
		sessionID uuid.UUID,
		workspace string,
		profileName string,
	) (*protocol.Worker, error)
	Current(sessionID uuid.UUID) (*protocol.Worker, bool)
}

WorkerSupervisor is the worker lifecycle the router needs.

It is an interface so the router depends on ensuring and cancelling a session's worker rather than on how one is launched.

type WorkspacePolicy

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

WorkspacePolicy admits only directories beneath an operator-configured root. It is the single place a client-supplied path becomes a host path, so the control surface never opens a directory the deployment did not allow.

func NewWorkspacePolicy

func NewWorkspacePolicy(roots []string) (*WorkspacePolicy, error)

NewWorkspacePolicy validates the operator's roots once at startup. Every root must already be absolute and canonical, which config.WorkspaceRoots guarantees, so a later request compares against a stable path.

func (*WorkspacePolicy) Resolve

func (p *WorkspacePolicy) Resolve(requested string) (string, error)

Resolve turns a requested workspace into the canonical path that identifies its session. It returns commerr.ErrNotFound when an admitted path does not exist, commerr.ErrValidationFailed for a path that is not a usable directory, and commerr.ErrPermissionDenied for one outside every configured root.

The path is resolved through its symlinks before the root check, so an alias of an allowed directory is admitted and resolves to the same session as the real path. Resolving first is also what stops a symlink inside an allowed root from reaching a directory outside it.

func (*WorkspacePolicy) Roots

func (p *WorkspacePolicy) Roots() []string

Roots returns the configured roots for reporting. The copy keeps a caller from rewriting the policy it is only meant to read.

Directories

Path Synopsis
Package client is the local control client behind Peen's CLI commands.
Package client is the local control client behind Peen's CLI commands.

Jump to

Keyboard shortcuts

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