managedagent

type ClusterEndpoint struct {
	BaseURL string
	// HostHeader carries the virtual host when the base URL is an IP. The
	// worker's ingress routes on Host, so omitting it lands on the default
	// backend and every call 404s while the address looks correct.
	HostHeader string
}

type ClusterResolver func(clusterID string) (ClusterEndpoint, bool)

type DerivedEnv struct {
	Name        string
	TemplateRef string
	Image       string
	Members     []DerivedMember
	Labels      map[string]string
	Annotations map[string]string
}

type DerivedMember struct {
	InstanceType string
	Resources    *corev1.ResourceRequirements
	Replicas     int32
	MinReplicas  int32
	MaxReplicas  int32
}

type HandsProvisioner interface {
	// EnsureEnv makes the env and its member pools exist, and reports whether
	// the env is serving. It must be safe to call on every reconcile.
	EnsureEnv(ctx context.Context, clusterID string, spec DerivedEnv) (ready bool, detail string, err error)

	// CreateEnv creates an env from a request body the caller supplies verbatim,
	// plus its member pools, and returns the env's name.
	//
	// Distinct from EnsureEnv in two ways that matter. It is a ONE-SHOT: the
	// caller is a console request, not a reconcile loop, so it reports a
	// conflict as an error instead of treating an existing env as success —
	// silently adopting somebody else's env would attach an agent to a sandbox
	// supply configured for another purpose. And the body is opaque here: it is
	// the worker's own create-env request, forwarded unchanged, so the console
	// can offer every field that API has (credential injection included) without
	// this type growing a mirror of it that drifts.
	CreateEnv(ctx context.Context, clusterID string, env json.RawMessage, members []json.RawMessage) (string, error)
}

type RESTHandsProvisioner struct {
	Resolve ClusterResolver
	// APIKey authenticates to every worker. The control plane acts as itself
	// here, not on behalf of the agent's owner: the env is platform
	// infrastructure and outlives any one caller's credential.
	APIKey string
	Client *http.Client
}

type Reconciler struct {
	client.Client
	Scheme *runtime.Scheme

	// ProxyService is this process reached from inside the cluster, as
	// "<service>.<namespace>:<port>". It is what status.endpoint points at so
	// in-cluster callers go through authentication too.
	ProxyService string

	// PublicBaseURL is the shared route this deployment serves published agents
	// on, e.g. "https://console.example.com/agentbox/api/managed-agents". Empty
	// leaves status.publicURL unset: the agent still works in-cluster, it just
	// has no address to hand out.
	PublicBaseURL string

	// Hands derives an agent's SandboxEnv on a worker cluster. It is nil on a
	// control plane with no worker clusters registered, which is why
	// spec.hands.auto reports "unavailable" instead of failing: the other two
	// hands modes stay usable.
	Hands HandsProvisioner

	// DefaultBrainImage is the image an agent gets when it names none, letting a
	// caller create one from a prompt alone. Unset keeps spec.image required.
	DefaultBrainImage agentsv1alpha1.ManagedAgentImage

	// DefaultHands is the sandbox supply an agent gets when it declares no branch.
	// Nil means a deployment that publishes none, and an agent without a branch
	// then reports HandsReady=False rather than coming up with no hands.
	DefaultHands *agentsv1alpha1.ManagedAgentHands

	// DefaultRuntime is the harness configuration — endpoint, models and
	// credential reference — an agent gets when it declares none of its own. Nil
	// leaves every agent to bring its own model credential.
	DefaultRuntime *agentsv1alpha1.ManagedAgentRuntime
}

type RenderDefaults struct {
	// BrainImage is used when the agent names no image of its own. Lets a caller
	// create an agent from a prompt alone, which is the point — requiring an image
	// reference means knowing which one carries a compatible gateway, and that is
	// the platform's business, not the tenant's.
	//
	// Empty keeps the image required, which is the correct behaviour for a
	// deployment that has not published one: inventing a reference would fail later
	// as an ImagePullBackOff, a long way from the cause.
	BrainImage agentsv1alpha1.ManagedAgentImage

	// Hands is the sandbox supply an agent gets when it declares no branch of its
	// own. The whole block is supplied, so a deployment can default to an external
	// service, a local SandboxEnv or a derived one without a second mechanism.
	//
	// It is applied on every render rather than stamped onto the object at creation:
	// the sandbox image travels with this default, and that tag rolls with its own
	// build, so a copy taken at creation time silently ages. Nil leaves an agent
	// without a branch with no supply at all, which the HandsReady condition
	// reports.
	Hands *agentsv1alpha1.ManagedAgentHands

	// Runtime is the harness configuration — endpoint, model list and credential
	// reference — an agent gets when it declares none of its own.
	//
	// This is the last thing standing between "create an agent from a prompt" and
	// an agent that cannot answer: a Brain with no model credential comes up
	// healthy, serves its API, and reports every harness unavailable. The failure
	// is legible but it is still an agent that does nothing.
	//
	// Whether a deployment SHOULD default this is its own call, and the two
	// answers are both reasonable. A shared internal endpoint makes one key
	// everyone's: one quota, one revocation, one audit trail. A deployment that
	// needs those separate leaves this unset and each agent brings its own. The
	// credential is a reference either way — this process renders a pointer and
	// never holds the key.
	Runtime *agentsv1alpha1.ManagedAgentRuntime
}

type Rendered struct {
	Deployment *appsv1.Deployment
	Service    *corev1.Service
	// PVC is nil when session persistence is disabled or supplied by an
	// existing claim.
	PVC *corev1.PersistentVolumeClaim
}