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
- func DialableAddress(listenAddress string) string
- type AdmissionWatcher
- type Core
- type EventRelay
- type EventSink
- type Handoff
- type OpenResult
- type Registry
- func (r *Registry) AgentSpaces() api.AgentSpaceList
- func (r *Registry) ListAgentSpaceDecisions(ctx context.Context, sessionID uuid.UUID, ...) (api.SessionAgentSpaceDecisionPage, error)
- func (r *Registry) ListSessions(ctx context.Context, params api.ListSessionsParams) (api.SessionPage, error)
- func (r *Registry) ListWorkerGenerations(ctx context.Context, sessionID uuid.UUID, params api.ListSessionWorkersParams) (api.WorkerGenerationPage, error)
- func (r *Registry) Open(ctx context.Context, requested string, agentSpaceName string) (OpenResult, error)
- func (r *Registry) OpenWorkspaceSession(ctx context.Context, workspace string, agentSpaceName string) (api.OpenedSession, error)
- func (r *Registry) ReconfigureSession(ctx context.Context, sessionID uuid.UUID, ...) (api.SessionAgentSpaceDecision, error)
- func (r *Registry) Roots() []string
- func (r *Registry) WorkspaceRoots() api.WorkspaceRootList
- type RegistryOptions
- type TurnRouter
- func (r *TurnRouter) CancelSessionTurn(ctx context.Context, sessionID uuid.UUID) (bool, error)
- func (r *TurnRouter) ReserveSessionMessage(sessionID uuid.UUID) *session.AdmissionTicket
- func (r *TurnRouter) RunReservedSessionMessage(ctx context.Context, reservation *session.AdmissionTicket, ...) (*agent.MessageRunResult, error)
- func (r *TurnRouter) RunSessionMessage(ctx context.Context, sessionID uuid.UUID, request agent.MessageRequest, ...) (*agent.MessageRunResult, error)
- func (r *TurnRouter) SignalSessionJob(ctx context.Context, sessionID uuid.UUID, jobID uuid.UUID, signal string) (*api.JobSignalResponse, error)
- type WorkerSupervisor
- type WorkspacePolicy
Constants ¶
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 ¶
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 AdmissionWatcher ¶ added in v0.17.0
type AdmissionWatcher interface {
WatchAdmission(
sessionID uuid.UUID,
requestID uuid.UUID,
admitted func(),
) func()
}
AdmissionWatcher reports when a session's worker admits a message.
It is an interface so the router depends on hearing about admission rather than on how worker events reach the controller.
type Core ¶
type Core struct {
Config peenconfig.Config
Upstreams []peenconfig.Upstream
Runtime *agent.Runtime
Store *session.Store
Handle *db.Handle
Sessions *Registry
// AgentSpaces are the deployment's allowed agent spaces. The API reads
// them so a client can see what it may name.
AgentSpaces *worker.AgentSpaceSet
// 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.
Every worker event passes through here, which also makes the relay the place the controller learns that a worker admitted a message.
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.
func (*EventRelay) WatchAdmission ¶ added in v0.17.0
func (r *EventRelay) WatchAdmission( sessionID uuid.UUID, requestID uuid.UUID, admitted func(), ) func()
WatchAdmission calls admitted once the session's worker admits the message sent under requestID.
A worker records userMessage.created for a message exactly when it admits it, whether the message starts a turn or joins the running turn's queue, and the record passes through this relay. admitted runs at most once, on the goroutine that publishes the event, so it must not block. The returned stop ends the watch and is safe to call after admitted has run.
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 ¶
Await returns the published Core, blocking until control-core publishes one or the context ends.
type OpenResult ¶
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) AgentSpaces ¶ added in v0.19.0
func (r *Registry) AgentSpaces() api.AgentSpaceList
AgentSpaces reports the agent spaces a client may name, with the grants of each Docker space and the capability warnings for any risky grant.
func (*Registry) ListAgentSpaceDecisions ¶ added in v0.19.0
func (r *Registry) ListAgentSpaceDecisions( ctx context.Context, sessionID uuid.UUID, params api.ListSessionAgentSpaceDecisionsParams, ) (api.SessionAgentSpaceDecisionPage, error)
ListAgentSpaceDecisions returns one page of a session's agent space 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, agentSpaceName 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, agentSpaceName 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 agent space the deployment does not offer, 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.SessionAgentSpaceDecision, error)
ReconfigureSession moves an idle session to a different agent space.
The agent space must be one the deployment offers, 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 in the new agent space rather than continuing in the old environment.
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
// AgentSpaces are the deployment's allowed agent spaces. A client names
// one when it opens a workspace, and an undefined name is refused.
AgentSpaces *worker.AgentSpaceSet
// Workers supervises each session's worker process. Reconfiguring a
// session stops its worker so the next turn starts a new generation in
// the new agent space. 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 agent space that session runs in, makes sure a worker for that agent space is live, then hands the turn over. The controller never runs the model loop itself.
Messages for one session reach its worker one at a time, in the order they were received. Each waits only until the worker has admitted the one before it, by starting a turn for it or queueing it, never for a whole turn.
func NewTurnRouter ¶
func NewTurnRouter( registry *Registry, workers WorkerSupervisor, admissionEvents AdmissionWatcher, ) (*TurnRouter, error)
NewTurnRouter binds the session registry to the worker supervisor. admissionEvents must observe the events the supervisor's workers publish, or each message would hold its session until its whole turn ended.
func (*TurnRouter) CancelSessionTurn ¶
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) ReserveSessionMessage ¶ added in v0.17.0
func (r *TurnRouter) ReserveSessionMessage( sessionID uuid.UUID, ) *session.AdmissionTicket
ReserveSessionMessage takes a message's place in its session's admission line without waiting. A caller that runs the message on another goroutine reserves first, so messages are admitted in the order it received them rather than the order its goroutines run in. The reservation must reach RunReservedSessionMessage or be released.
func (*TurnRouter) RunReservedSessionMessage ¶ added in v0.17.0
func (r *TurnRouter) RunReservedSessionMessage( ctx context.Context, reservation *session.AdmissionTicket, request agent.MessageRequest, requestID uuid.UUID, ) (*agent.MessageRunResult, error)
RunReservedSessionMessage runs one message in its session's worker once its reservation is admitted, and releases the reservation.
The session is loaded first, so a message naming a session that does not exist fails before any worker is started. The agent space comes from the stored session rather than the request: the agent space is a decision recorded at open or reconfigure time, never something a message carries.
The reservation is held while the worker is ensured, so concurrent messages cannot launch two workers for one session, and until the worker admits the message. The worker reports admission through the message's userMessage.created event; a call that ends first, by failing or by answering, releases it too.
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 message in the session's worker, reserving its place in the session's admission line on entry.
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,
agentSpaceName 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.