pkg

type AgentCardConfig ¶ added in v0.2.0

type AgentCardConfig struct {
	// Name names the deployed agent in the Agent Card.
	Name string
	// PublicURL is the externally reachable A2A endpoint the card advertises verbatim.
	// It is never derived from the listen address or a request header.
	PublicURL string
}

AgentCardConfig is what the A2A Agent Card advertises about this service.

type Backend ¶

type Backend string

Backend names the implementation that serves workers. Its value space belongs to the backend implementations and to the selection wiring, never to this schema: a constant naming a backend here would put that backend's identity above the seam this package exists to hold, and a second backend would have to edit the shared schema to become selectable.

const (
	// BackendDocker runs each worker as a container on the local host.
	BackendDocker Backend = "docker"
	// BackendKubernetes runs each worker as a workload in the cluster.
	BackendKubernetes Backend = "k8s"
)

type BackendProvider ¶ added in v0.2.0

type BackendProvider interface {
	// Get returns the backend serving the named backend, or an error when the name is
	// not one the controller knows or its implementation is not wired.
	Get(ctx context.Context, backend Backend) (WorkerBackend, error)
}

BackendProvider resolves a backend name to the WorkerBackend that serves it.

func NewBackendProvider(docker WorkerBackend, kubernetes WorkerBackend) BackendProvider

type ControlRequest ¶

type ControlRequest struct {
	Operation Operation `json:"operation"`
	// Create is set when Operation is OperationCreate.
	Create *CreateRequest `json:"create,omitempty"`
	// Stop is set when Operation is OperationStop.
	Stop *StopRequest `json:"stop,omitempty"`
}

ControlRequest is one control-API call. Exactly one operation-specific field is set and it matches Operation; a request that sets none, or more than one, is refused rather than guessed at.

type ControlResponse ¶

type ControlResponse struct {
	Operation Operation       `json:"operation"`
	Create    *CreateResponse `json:"create,omitempty"`
	List      *ListResponse   `json:"list,omitempty"`
	Stop      *StopResponse   `json:"stop,omitempty"`
}

ControlResponse is the controller's reply to one ControlRequest. Exactly one operation-specific field is set and it matches Operation.

type CreateRequest ¶

type CreateRequest struct {
	Task TaskName `json:"task"`
}

CreateRequest asks for a worker serving one task.

type CreateResponse ¶

type CreateResponse struct {
	Worker Worker `json:"worker"`
	// Token is the worker's own bearer credential. It must never be logged, echoed into a
	// transcript, or written to a file.
	Token string `json:"token"`
}

CreateResponse is the reply to a create. It is the only place a worker's token is ever returned: the controller keeps no copy it depends on, so a caller that loses this reply stops the worker and creates another rather than asking the controller to repeat it.

type ListResponse ¶

type ListResponse struct {
	Workers []Worker `json:"workers"`
}

ListResponse is the reply to a list.

type Operation ¶

type Operation string

Operation names one control-API operation. It travels as a plain string so a caller written against this schema needs no shared Go type to address the controller.

const (
	// OperationCreate asks the controller for a worker serving one task.
	OperationCreate Operation = "create"
	// OperationList asks the controller for every worker it owns.
	OperationList Operation = "list"
	// OperationStop asks the controller to stop and remove one worker.
	OperationStop Operation = "stop"
)

type StopRequest ¶

type StopRequest struct {
	WorkerID WorkerID `json:"worker_id"`
}

StopRequest names the worker to stop and remove.

type StopResponse ¶

type StopResponse struct {
	Worker Worker `json:"worker"`
}

StopResponse is the reply to a stop. It carries the stopped worker so a caller can confirm which one the controller acted on.

type StubWorkerBackend ¶ added in v0.2.0

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

StubWorkerBackend is a throwaway in-memory WorkerBackend. It exists for two reasons.

It makes the executor testable with no container, no cluster and no credential: a test drives the real executor and the real selection wiring against it. And it is the second implementation of WorkerBackend, which is what proves the seam — the executor drives it through the same interface it drives a real backend through, without knowing which one it holds.

It is absent from the selection wiring in backend-provider.go: no Backend value resolves to it. It is therefore reachable only by tests and by explicit construction, and can never serve a production request.

func NewStubWorkerBackend() *StubWorkerBackend

func (s *StubWorkerBackend) Create(
	ctx context.Context,
	req CreateRequest,
) (*CreateResponse, error)

func (s *StubWorkerBackend) List(ctx context.Context) (*ListResponse, error)

func (s *StubWorkerBackend) Stop(ctx context.Context, req StopRequest) (*StopResponse, error)

type TaskName ¶

type TaskName string

TaskName is the vault task a worker serves. It names the work, not the worker — a task has at most one worker, and a second create for a task that already has one returns the existing worker rather than starting another.

type Worker ¶

type Worker struct {
	WorkerID WorkerID    `json:"worker_id"`
	Task     TaskName    `json:"task"`
	A2AURL   string      `json:"a2a_url"`
	Backend  Backend     `json:"backend"`
	State    WorkerState `json:"state"`
}

Worker is one worker as the control API reports it. It deliberately carries no token: a worker's token is returned once by create and never again, so no listing, no log and no restart can leak one.

type WorkerBackend ¶ added in v0.2.0

type WorkerBackend interface {
	// Create starts one worker serving the requested task and returns it together with
	// its own bearer token. A task that already has a worker returns the existing one
	// rather than starting a second.
	Create(ctx context.Context, req CreateRequest) (*CreateResponse, error)

	// List returns every worker the backend owns. It is rebuilt from the backend's own
	// resource state on every call, never from controller memory, so a controller
	// restart loses nothing.
	List(ctx context.Context) (*ListResponse, error)

	// Stop stops and removes the named worker and returns it.
	Stop(ctx context.Context, req StopRequest) (*StopResponse, error)
}

WorkerBackend is the single seam every backend implements. It is expressible with the control-API schema alone: it takes the schema's request shapes and returns its response shapes, so nothing above the seam names a backend and a new backend needs no change to the schema, to the executor or to the HTTP surface.

type WorkerID ¶

type WorkerID string

WorkerID identifies one worker the controller created. It is the value a caller passes back to stop a worker and the value list reports, so it stays stable across a controller restart: it is read back from the worker's own labels rather than minted per request and held in memory.

type WorkerState ¶

type WorkerState string

WorkerState is what list reports about a worker's lifecycle.

const (
	// WorkerStateRunning means the worker exists and answers on its own A2A URL.
	WorkerStateRunning WorkerState = "running"
	// WorkerStateStopped means the worker no longer exists. It appears only in the reply to
	// the stop that removed it; list never returns it.
	WorkerStateStopped WorkerState = "stopped"
	// WorkerStateUnknown means the worker's backing resource exists but the controller
	// cannot classify it, so a caller must not read it as running.
	WorkerStateUnknown WorkerState = "unknown"
)