v1alpha1

type BackendStatus struct {
	// +required
	ID string `json:"id"`
	// +optional
	Available bool `json:"available,omitempty"`
	// +optional
	Reason string `json:"reason,omitempty"`
}

type ClaudeCodeRuntime struct {
	// BaseURL is an Anthropic-format endpoint. Empty means api.anthropic.com.
	// +optional
	BaseURL string `json:"baseURL,omitempty"`

	// CredentialsRef supplies ANTHROPIC_AUTH_TOKEN.
	// +required
	CredentialsRef SecretKeySelector `json:"credentialsRef"`

	// Models is the ONLY source of the in-composer dropdown. The Claude Agent
	// SDK's supportedModels() is a static table compiled into the SDK and never
	// queries the endpoint, so a configured list is the only correct answer.
	// +optional
	Models []ManagedAgentModel `json:"models,omitempty"`

	// +optional
	DefaultModel string `json:"defaultModel,omitempty"`

	// SmallModel backs the harness's own side tasks (titles and the like).
	// +optional
	SmallModel string `json:"smallModel,omitempty"`

	// +kubebuilder:validation:Enum=low;medium;high;xhigh;max
	// +optional
	Effort string `json:"effort,omitempty"`

	// PluginPaths are in-image plugin directories carrying skills, sub-agents,
	// hooks and .mcp.json. They coexist with an empty settingSources, which is
	// how product assets load without reading a developer's own ~/.claude.
	// +optional
	PluginPaths []string `json:"pluginPaths,omitempty"`
}

type ClientToolSpec struct {
	// +required
	Name string `json:"name"`
	// +required
	Description string `json:"description"`
	// InputSchema is JSON Schema, passed to the harness unchanged.
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	InputSchema *apiextensionsv1.JSON `json:"inputSchema,omitempty"`
	// TimeoutSeconds bounds how long the platform waits for the caller.
	// +optional
	TimeoutSeconds int32 `json:"timeoutSeconds,omitempty"`
}

type ConfigMapKeySelector struct {
	// +required
	Name string `json:"name"`
	// +required
	Key string `json:"key"`
}

type EgressRules struct {
	// AllowedDomains permits egress to matching hostnames. Supports exact
	// ("pypi.org"), wildcard-all ("*"), and suffix ("*.pythonhosted.org").
	// Matched via TLS SNI (443) / HTTP Host (80); other ports are IP-only.
	// +optional
	AllowedDomains []string `json:"allowedDomains,omitempty"`

	// AllowedCIDRs permits egress to these CIDR blocks / bare IPs (as /32).
	// +optional
	AllowedCIDRs []string `json:"allowedCIDRs,omitempty"`

	// DeniedCIDRs blocks egress to these CIDR blocks / bare IPs. Domains are not
	// supported for deny (a domain resolves to many changing IPs).
	// +optional
	DeniedCIDRs []string `json:"deniedCIDRs,omitempty"`
}

type EmbeddedSandboxTemplate struct {
	// Template defines the Pod template. ALL Pods in this Pool share the same
	// resources (requests/limits). The image specified here is used as the IDLE image
	// unless IdleImage is explicitly set.
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Schemaless
	// +optional
	Template corev1.PodTemplateSpec `json:"template,omitempty"`

	// IdleImage is the image to use when Pods are in the idle state.
	// If not specified, the image from Template.Spec.Containers[0].Image will be used.
	// +optional
	IdleImage string `json:"idleImage,omitempty"`

	// Runtimes specifies the runtimes to use for the sandbox pods. Each runtime has a type and optional configuration.
	// If not specified, a default runtime will be used.
	// +listType=map
	// +listMapKey=name
	// +optional
	Runtimes []SandboxRuntimeSpec `json:"runtimes,omitempty"`
}

type EnvAutoscalingGroup struct {
	// Name matches EnvClusterMember.ScalingGroup. Required. The Env
	// rejects groups whose Name does not match the ScalingGroup of at
	// least one member — empty-group policies have no effect and would
	// confuse the autoscaler's per-group iteration.
	// +required
	Name string `json:"name"`

	// Enabled toggles the autoscaler on/off for this group. When false,
	// member Pool replicas in this scaling group are managed manually.
	// +optional
	// +kubebuilder:default=false
	Enabled bool `json:"enabled,omitempty"`

	// MinReplicas is the lower bound for the aggregate (group) replica
	// count. Defaults to 0 — set explicitly so kubectl get sbe surfaces
	// the floor instead of leaving it implicit.
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:default=0
	MinReplicas *int32 `json:"minReplicas,omitempty"`

	// MaxReplicas is the upper bound for the aggregate (group) replica
	// count. When unset, the group has NO ceiling and grows until each
	// member's own MaxReplicas, the cluster's capacity, or external
	// quotas stop it. Aggressive scaleUpPolicy.mode REQUIRES this field
	// to be set (validated via CEL) because doubling each cooldown
	// without an upper bound is unsafe.
	// +optional
	// +kubebuilder:validation:Minimum=0
	MaxReplicas *int32 `json:"maxReplicas,omitempty"`

	// ScaleUpPolicy controls how scale-up decisions are evaluated. The
	// API server fills every field with its declared default when the
	// caller omits it, so the persisted CR always carries an explicit,
	// inspectable value (no hidden code defaults).
	// +optional
	// +kubebuilder:default={}
	ScaleUpPolicy PoolScaleUpPolicy `json:"scaleUpPolicy"`

	// ScaleDownPolicy controls how scale-down decisions are evaluated.
	// Same defaulting contract as ScaleUpPolicy.
	// +optional
	// +kubebuilder:default={}
	ScaleDownPolicy PoolScaleDownPolicy `json:"scaleDownPolicy"`
}

type EnvAutoscalingSpec struct {
	// Groups is the list of autoscaling groups. Each group is keyed by Name
	// and toggles its own Enabled bit independently.
	// +optional
	// +listType=map
	// +listMapKey=name
	Groups []EnvAutoscalingGroup `json:"groups,omitempty"`
}

type EnvClusterMember struct {
	// Name is the SandboxPool's metadata.name within the Env's namespace.
	// Acts as the list map key for Members. Must equal Metadata.Name once
	// the Reconciler materialises the Pool; the Reconciler overwrites
	// Metadata.Name with Name at stamp time if they disagree.
	// +required
	Name string `json:"name"`

	// Metadata is the snapshot of the candidate Pool's mutable ObjectMeta
	// subset (Labels + Annotations) after PreCreatePool. The Reconciler
	// propagates these onto the live Pool when materialising it.
	//
	// Finalizers are intentionally NOT stored here — `SandboxPoolReconciler`
	// owns the Pool's finalizer lifecycle. Name/Namespace/UID/etc. are server
	// or Env-owned and don't belong on a per-member snapshot. Using a
	// dedicated struct (instead of metav1.ObjectMeta) avoids controller-gen
	// emitting a degenerate `type: object` schema, which K8s API server would
	// otherwise prune in admission.
	// +optional
	Metadata MemberMetadata `json:"metadata,omitempty"`

	// Spec is the snapshot of the candidate SandboxPoolSpec after
	// PreCreatePool. The Reconciler stamps the whole Spec verbatim when
	// creating the live Pool and uses equality.Semantic.DeepEqual to
	// detect drift between Spec and the live Pool on subsequent
	// reconciles, including Spec.Replicas. The Env Reconciler is the
	// sole writer of the live Pool's Replicas — both the API
	// (UpdateMember) and the Env autoscaler express their intent by
	// patching Member.Spec.Replicas here and let the Reconciler
	// propagate it.
	// +optional
	Spec SandboxPoolSpec `json:"spec,omitempty"`

	// Config carries user-declared intent: sizing (InstanceType/Multiplier
	// or InlineResources), autoscaling bookkeeping (ScalingGroup,
	// MaxReplicas), and routing priorities. Plugins do not mutate Config,
	// so it remains a faithful description of the caller's request.
	// +optional
	Config EnvClusterMemberConfig `json:"config,omitempty"`
}

type EnvClusterMemberConfig struct {
	// Labels are caller-supplied SandboxPool metadata.labels stamped onto
	// the rendered candidate Pool BEFORE PreCreatePool runs. Plugins
	// typically consume these for routing decisions (e.g. the
	// "quota.scitix.ai/url" label selects which ScitixQuota CR backs the
	// member). The plugin output — original + any plugin-added labels —
	// lands in Member.Metadata.Labels; Config.Labels stays equal to the
	// caller's input.
	// +optional
	Labels map[string]string `json:"labels,omitempty"`

	// Annotations are caller-supplied SandboxPool metadata.annotations,
	// same propagation rules as Labels.
	// +optional
	Annotations map[string]string `json:"annotations,omitempty"`

	// InstanceType references an entry in the cluster-wide InstanceType
	// catalog. Mutually informative with InlineResources: if both are set,
	// InstanceType wins and InlineResources serves as a transitional
	// record for migration.
	// +optional
	InstanceType string `json:"instanceType,omitempty"`

	// Multiplier scales InstanceType's resources. Required when
	// InstanceType is set.
	// +optional
	// +kubebuilder:validation:Minimum=0
	Multiplier int32 `json:"multiplier,omitempty"`

	// InlineResources is the Phase 1 migration escape hatch (legacy Pools
	// without an InstanceType label) AND the source of truth used by a
	// future RefreshMember API to keep resource sizing stable when the
	// underlying Template is upgraded. New Envs created via the Dashboard
	// should leave this empty and use InstanceType+Multiplier instead.
	// +optional
	InlineResources *corev1.ResourceRequirements `json:"inlineResources,omitempty"`

	// ScalingGroup names the autoscaling group this member belongs to.
	// Members in the same group must share the same effective resources
	// (= InstanceType × Multiplier or identical InlineResources). Empty
	// means the member is excluded from autoscaling.
	// +optional
	// +kubebuilder:default=default
	ScalingGroup string `json:"scalingGroup,omitempty"`

	// MinReplicas is the lower bound on this member's spec.replicas.
	// Enforced by the Env autoscaler: scale-down never shrinks this member
	// below MinReplicas. nil/0 means no per-member floor (only the group's
	// aggregate MinReplicas applies).
	// +optional
	// +kubebuilder:validation:Minimum=0
	MinReplicas *int32 `json:"minReplicas,omitempty"`

	// MaxReplicas is the upper bound on this member's spec.replicas.
	// Enforced by the Env autoscaler when distributing scale-up delta
	// across members.
	// +optional
	// +kubebuilder:validation:Minimum=0
	MaxReplicas *int32 `json:"maxReplicas,omitempty"`

	// Priority is the canonical routing/scaling preference: lower wins.
	// Also acts as the default for ScaleUpPriority / ScaleDownPriority
	// when those are unset.
	// +optional
	Priority int32 `json:"priority,omitempty"`

	// ScaleUpPriority overrides Priority for scale-up ordering within a
	// scalingGroup. Same-value tiebreak: (clusterID, name) lexicographic.
	// When nil, EffectiveScaleUpPriority falls back to Priority.
	// Reserved for Phase 2; Phase 1 ignores it.
	// +optional
	ScaleUpPriority *int32 `json:"scaleUpPriority,omitempty"`

	// ScaleDownPriority overrides Priority for scale-down ordering: lower
	// values are retained, higher values shrink first. The value direction
	// is intentionally inverted from ScaleUpPriority so that a single
	// Priority value (lower wins) means "preferred member" in both
	// directions — preferred members scale up first AND scale down last.
	// Same-value tiebreak: oldest idle Pod first, then name lexicographic.
	// When nil, EffectiveScaleDownPriority falls back to Priority.
	// +optional
	ScaleDownPriority *int32 `json:"scaleDownPriority,omitempty"`

	// UpdateStrategy overrides the Env-wide overrides.updateStrategy for this
	// member only. Unset fields inherit from the Env default, then from the
	// hard-coded default (autoUpdate=true, maxUnavailable="20%"). See
	// ResolveAutoUpdate / ResolveMaxUnavailable.
	// +optional
	UpdateStrategy *EnvUpdateStrategy `json:"updateStrategy,omitempty"`
}

type EnvClusterSpec struct {
	// ClusterID identifies the cluster that owns this segment. Each Worker
	// only mutates the segment matching its own ClusterID.
	// +required
	ClusterID string `json:"clusterID"`

	// Members is the list of SandboxPool members contributed by this cluster.
	// Phase 1 supports exactly one member per cluster.
	// +optional
	// +listType=map
	// +listMapKey=name
	Members []EnvClusterMember `json:"members,omitempty"`
}

type EnvClusterStatus struct {
	// ClusterID matches the spec's ClusterID for the same segment.
	// +required
	ClusterID string `json:"clusterID"`

	// IsLocal is true on the Worker that owns this cluster's Pools. Used to
	// gate writes: only IsLocal=true segments are mutated by the local Env
	// Reconciler.
	// +optional
	IsLocal bool `json:"isLocal,omitempty"`

	// ObservedMembers reports per-member runtime state (idle/running/desired,
	// effective resources, member state).
	// +optional
	// +listType=map
	// +listMapKey=name
	ObservedMembers []EnvObservedMember `json:"observedMembers,omitempty"`

	// LastSnapshotTime records when this segment was last updated. For
	// IsLocal=true: write time by the local Reconciler. For IsLocal=false:
	// arrival time of the Hub Sync push.
	// +optional
	LastSnapshotTime *metav1.Time `json:"lastSnapshotTime,omitempty"`
}

type EnvObservedMember struct {
	// Name matches the spec member's Name and is the list map key.
	// +required
	Name string `json:"name"`

	// InstanceType / Multiplier are echoed from spec for convenience.
	// +optional
	InstanceType string `json:"instanceType,omitempty"`
	// +optional
	Multiplier int32 `json:"multiplier,omitempty"`

	// EffectiveResources is the resolved resource request/limit per Pod
	// (= InstanceType.resources × Multiplier, or InlineResources verbatim).
	// +optional
	EffectiveResources *corev1.ResourceRequirements `json:"effectiveResources,omitempty"`

	// State summarises whether the member can currently serve requests.
	// +optional
	State ObservedMemberState `json:"state,omitempty"`

	// IdleCount, RunningCount are mirrored from SandboxPool.status to surface
	// a single Env-level view to the Dashboard.
	// +optional
	IdleCount int32 `json:"idleCount,omitempty"`
	// +optional
	RunningCount int32 `json:"runningCount,omitempty"`

	// DesiredReplicas is the most recent value the Env autoscaler patched onto
	// the member Pool's spec.replicas.
	// +optional
	DesiredReplicas int32 `json:"desiredReplicas,omitempty"`

	// CurrentReplicas is the value last observed on the Pool spec.
	// +optional
	CurrentReplicas int32 `json:"currentReplicas,omitempty"`

	// PendingRequests is the throttled mirror of the in-process PoolScheduler
	// claim queue length, copied from SandboxPool.Status.PendingRequests.
	// Used by Dashboard observability and (future) cross-cluster routing.
	// +optional
	PendingRequests int32 `json:"pendingRequests,omitempty"`

	// SaturatedUntil marks this member as ineligible for routing/scaling
	// until the given time. Read-only mirror of
	// SandboxPool.Status.AutoScaling.SaturatedUntil, refreshed by the Env
	// reconciler's status aggregation; the source of truth is the per-Pool
	// autoscaler. The router (EnvScheduler) holds saturated members back
	// from the primary candidate list but still tries them as fallback
	// when no fresh member can accept the request.
	// +optional
	SaturatedUntil *metav1.Time `json:"saturatedUntil,omitempty"`

	// ScalingGroup is the autoscaling group this member belongs to on its
	// owning cluster, echoed from spec for convenience. Empty when the
	// member is not in any group. Lets a cross-cluster view (where the
	// consumer does not hold the foreign cluster's spec) still attribute
	// the member to a group and link to that cluster's group detail.
	// +optional
	ScalingGroup string `json:"scalingGroup,omitempty"`

	// AutoscalingEnabled reports whether this member's ScalingGroup has the
	// autoscaler turned on in its owning cluster. Because each cluster
	// controls its own scaling independently, a same-named group may be
	// enabled in one cluster and disabled in another; this is the per-pool,
	// per-cluster truth. It disambiguates ScaleUpHeadroom == 0 (at ceiling)
	// from autoscaling being off entirely.
	// +optional
	AutoscalingEnabled bool `json:"autoscalingEnabled,omitempty"`

	// ScaleUpHeadroom estimates how many more replicas this member can still
	// add on its owning cluster before hitting the smaller of its own
	// MaxReplicas and its group's aggregate MaxReplicas (given the group's
	// current total desired). It is meaningful only when AutoscalingEnabled
	// is true:
	//   - nil  → autoscaling off, or enabled with no finite ceiling (unbounded)
	//   - 0    → enabled but already at the ceiling (cannot grow now)
	//   - >0   → enabled with this much room left
	// The value is an estimate: the group ceiling is shared across members
	// and quota/node capacity are not folded in, so treat it as advisory
	// (like idle counts, it also lags by the federation TTL for foreign
	// members).
	// +optional
	ScaleUpHeadroom *int32 `json:"scaleUpHeadroom,omitempty"`

	// UpdateRevision is the target revision hash the member Pool is rolling
	// towards, mirrored from SandboxPool.Status.UpdateRevision.
	// +optional
	UpdateRevision string `json:"updateRevision,omitempty"`

	// TemplateVersion is the SandboxTemplate spec.version the member Pool was
	// last rendered from, read off the Pool's
	// agentbox.navix.sh/template-version provenance annotation. It is an
	// observation, not a constraint: members follow the Template's current
	// body, so this reports what they actually carry. Empty for foreign
	// (cross-cluster) members — the federation payload does not carry it.
	// +optional
	TemplateVersion string `json:"templateVersion,omitempty"`

	// UpdatedReplicas is the number of the member Pool's Pods already at
	// UpdateRevision, mirrored from SandboxPool.Status.UpdatedReplicas. A
	// rollout is in progress while UpdatedReplicas < the member's replicas.
	// +optional
	UpdatedReplicas int32 `json:"updatedReplicas,omitempty"`
}

type EnvOverridesSpec struct {
	// Image overrides the main container (containers[0]) image of the
	// rendered Template. Applied before any per-Member overrides.
	// +optional
	Image string `json:"image,omitempty"`

	// PodCreationImagePolicy overrides the Template's
	// spec.podCreationImagePolicy. Applied to every member Pool.
	// +optional
	// +kubebuilder:validation:Enum=PoolDefaultImage;IdleImage
	PodCreationImagePolicy PodCreationImagePolicy `json:"podCreationImagePolicy,omitempty"`

	// DefaultStartupTimeout overrides the Template's
	// spec.defaultStartupTimeout. Applied to Sandbox.Create requests that
	// don't carry an explicit startupTimeout.
	// +optional
	DefaultStartupTimeout *metav1.Duration `json:"defaultStartupTimeout,omitempty"`

	// DefaultIdleTimeout overrides the Template's spec.defaultIdleTimeout.
	// Applied to Sandboxes that don't carry an explicit idleTimeout.
	// +optional
	DefaultIdleTimeout *metav1.Duration `json:"defaultIdleTimeout,omitempty"`

	// NetworkPolicy, when set, enables sandbox egress filtering for every member
	// Pool of this Env. The operator injects a transparent filter sidecar into
	// each sandbox Pod; this policy is the Env-wide default, overridable per
	// sandbox at create time. Nil disables egress filtering (no sidecar).
	// +optional
	NetworkPolicy *SandboxNetworkPolicy `json:"networkPolicy,omitempty"`

	// UpdateStrategy is the Env-wide default rollout policy: when a member's
	// effective idle-Pod identity changes (Template edit, image / networkPolicy
	// override), whether and how fast its idle Pods are rebuilt. Per-member
	// EnvClusterMemberConfig.UpdateStrategy overrides this; see ResolveAutoUpdate
	// / ResolveMaxUnavailable for the resolution order.
	// +optional
	UpdateStrategy *EnvUpdateStrategy `json:"updateStrategy,omitempty"`
}

type EnvScalingGroupStatus struct {
	// Name matches the autoscaling group's Name and is the list map key.
	// +required
	Name string `json:"name"`

	// TotalIdle / TotalRunning / TotalDesired aggregate across members.
	// +optional
	TotalIdle int32 `json:"totalIdle,omitempty"`
	// +optional
	TotalRunning int32 `json:"totalRunning,omitempty"`
	// +optional
	TotalDesired int32 `json:"totalDesired,omitempty"`
}

type EnvUpdateStrategy struct {
	// AutoUpdate toggles automatic rollout. When nil the value is inherited
	// (member → env → default true). Set false to freeze a member on its
	// current revision (e.g. to pin a fleet during an incident).
	// +optional
	AutoUpdate *bool `json:"autoUpdate,omitempty"`

	// MaxUnavailable bounds how many of a member Pool's desired idle Pods may be
	// unavailable at once during a rollout, as an absolute number or a
	// percentage of desired replicas (e.g. "20%"). Rounded down, floored at 1 so
	// small pools still make progress. When nil the value is inherited
	// (member → env → default "20%").
	// +optional
	// +kubebuilder:validation:XIntOrString
	MaxUnavailable *intstr.IntOrString `json:"maxUnavailable,omitempty"`
}

type HandsAutoSpec struct {
	// +required
	ClusterID string `json:"clusterID"`
	// +required
	TemplateRef string `json:"templateRef"`
	// +optional
	Image string `json:"image,omitempty"`
	// +required
	InstanceTypes []HandsInstanceType `json:"instanceTypes"`
	// +optional
	IdleTimeoutSeconds int32 `json:"idleTimeoutSeconds,omitempty"`
	// +optional
	StartupTimeoutSeconds int32 `json:"startupTimeoutSeconds,omitempty"`
}

type HandsBinding struct {
	// Scope is the granularity a sandbox is bound at.
	// +kubebuilder:validation:Enum=thread;user
	// +kubebuilder:default=thread
	// +optional
	Scope string `json:"scope,omitempty"`

	// TimeoutSeconds is the sandbox IDLE timeout.
	// +optional
	TimeoutSeconds int32 `json:"timeoutSeconds,omitempty"`

	// ReadyTimeoutSeconds bounds how long a cold image pull may take.
	//
	// Note that readiness is not the same as usability: the sandbox API reports
	// a sandbox running before envd accepts commands, so callers must retry the
	// first command rather than trust the readiness flag alone.
	// +optional
	ReadyTimeoutSeconds int32 `json:"readyTimeoutSeconds,omitempty"`

	// AttachmentRoot is where staged attachments are flushed inside the sandbox,
	// written as root and world-readable so the agent can read but not alter
	// them.
	// +optional
	AttachmentRoot string `json:"attachmentRoot,omitempty"`

	// +optional
	MaxAttachmentBytes int64 `json:"maxAttachmentBytes,omitempty"`

	// Workspace is the FALLBACK sandbox working directory, used only when the
	// per-user directory cannot be resolved.
	// +optional
	Workspace string `json:"workspace,omitempty"`

	// SkipSeed suppresses the daemon's workspace seeding for images that already
	// carry it.
	// +optional
	SkipSeed bool `json:"skipSeed,omitempty"`

	// SeedRepo is cloned into the workspace on sandbox creation. Ignored when
	// SkipSeed is set.
	// +optional
	SeedRepo string `json:"seedRepo,omitempty"`
}

type HandsE2B struct {
	// CredentialsSecret carries E2B_API_KEY and AGBX_ENV_NAME, optionally
	// AGBX_HTTPS / E2B_DOMAIN / E2B_API_URL. It is consumed with envFrom, so
	// the Brain never has these values inlined in its pod spec.
	// +optional
	CredentialsSecret string `json:"credentialsSecret,omitempty"`
	// +optional
	APIURL string `json:"apiURL,omitempty"`
	// +optional
	Domain string `json:"domain,omitempty"`
	// +optional
	HTTPS *bool `json:"https,omitempty"`
}

type HandsEnvRef struct {
	// ClusterID scopes the env to one cluster. Empty means the local cluster.
	// +optional
	ClusterID string `json:"clusterID,omitempty"`
	// +required
	Name string `json:"name"`
	// Namespace of the SandboxEnv; empty means the agent's namespace.
	// +optional
	Namespace string `json:"namespace,omitempty"`
	// ScalingGroup pins every sandbox to one member pool unless a scenario
	// overrides it.
	// +optional
	ScalingGroup string `json:"scalingGroup,omitempty"`
	// Image overrides the sandbox main container image.
	//
	// Leaving this empty is not equivalent to "use a sensible default": a pool's
	// default image does not run envd, so sandboxes created without an override
	// come up and then answer every command with a 502. Either set it here or on
	// every scenario.
	// +optional
	Image string `json:"image,omitempty"`
}

type HandsExternal struct {
	// APIURL is the E2B-compatible control endpoint.
	// +required
	APIURL string `json:"apiURL"`

	// Domain is the data-plane gateway, host plus any ingress path. Omitting the
	// path is the usual cause of "the sandbox exists but no port answers".
	// +required
	Domain string `json:"domain"`

	// +kubebuilder:default=true
	// +optional
	HTTPS *bool `json:"https,omitempty"`

	// EnvName is the name to launch from at the remote, written verbatim: a bare
	// environment ("navix"), or one scoped to a cluster ("cluster::navix").
	// +required
	EnvName string `json:"envName"`

	// Image overrides the sandbox main container image.
	//
	// A pool's default image does not run the sandbox command endpoint, so
	// leaving this empty yields sandboxes that start and then refuse every
	// command, with no error on the control plane.
	// +optional
	Image string `json:"image,omitempty"`

	// ScalingGroup pins every sandbox to one member pool at the remote.
	// +optional
	ScalingGroup string `json:"scalingGroup,omitempty"`

	// CredentialsRef supplies the remote's API key.
	// +optional
	CredentialsRef *SecretKeySelector `json:"credentialsRef,omitempty"`
}

type HandsInstanceType struct {
	// Name is the member's identity. It is the instance-type catalog entry on
	// a cluster that has the catalog enabled, and the scaling group otherwise;
	// either way it is the name sandboxes are routed to.
	// +required
	Name string `json:"name"`

	// Resources sizes the member directly, for clusters with no instance-type
	// catalog. Setting it switches the member from a catalog lookup to an
	// inline size — on a cluster without a catalog, a member that only names
	// an instance type is rejected, and on one with a catalog these two ways
	// of sizing are mutually exclusive.
	// +optional
	Resources *corev1.ResourceRequirements `json:"resources,omitempty"`

	// +optional
	Replicas int32 `json:"replicas,omitempty"`
	// +optional
	MinReplicas *int32 `json:"minReplicas,omitempty"`
	// +optional
	MaxReplicas *int32 `json:"maxReplicas,omitempty"`
	// +optional
	Default bool `json:"default,omitempty"`
}

type HeaderInjection struct {
	// Name is the header name, compared case-insensitively.
	Name string `json:"name"`

	// Value is a template that may reference declared credentials by name, each
	// name wrapped in a doubled pair of curly braces. For an Authorization
	// header, that is a Bearer prefix followed by the brace-wrapped name of the
	// credential holding the key.
	Value string `json:"value"`

	// Mode defaults to Override.
	// +optional
	Mode HeaderInjectionMode `json:"mode,omitempty"`
}

type HeaderInjectionMode string

type InjectedCredential struct {
	// Name is how rules refer to this credential in a value template: the
	// credential name wrapped in a doubled pair of curly braces.
	Name string `json:"name"`

	// ValueFrom points at the Secret key holding the credential. The Secret
	// must live in the SandboxEnv's namespace.
	ValueFrom SecretKeyRef `json:"valueFrom"`

	// ExposeAs turns on placeholder mode: the sandbox gets an environment
	// variable of this name whose value is a decoy (see Placeholder), and the
	// proxy swaps the decoy for the real value on hosts that allow it. Leave
	// empty to use the credential through header injection only.
	// +optional
	ExposeAs string `json:"exposeAs,omitempty"`

	// Placeholder is the decoy value handed to the sandbox. Empty means a fresh
	// random "agbx_ph_<32 hex>" per claim.
	//
	// Set it when a client validates credential shape before sending — several
	// SDKs reject a key that lacks the expected prefix or length, so a random
	// decoy would fail inside the sandbox and never reach the proxy. A fixed
	// decoy costs nothing in secrecy (it already lives in the sandbox's
	// environment); it is merely identical across sandboxes.
	//
	// Must be at least 16 characters, and no two credentials may share a
	// placeholder or have one be a substring of another — overlapping decoys
	// would substitute into each other.
	// +optional
	Placeholder string `json:"placeholder,omitempty"`
}

type InjectionRule struct {
	// Host must be an exact hostname. Wildcards are rejected: anyone able to
	// control a matching subdomain would receive the credential.
	Host string `json:"host"`

	// Ports narrows which destination ports the rule covers. Defaults to
	// [80, 443]; other ports get no L7 handling at all.
	// +optional
	Ports []int32 `json:"ports,omitempty"`

	// Headers are the headers to inject.
	// +optional
	Headers []HeaderInjection `json:"headers,omitempty"`

	// Substitute lists credentials whose placeholder may be swapped for the
	// real value on this host.
	// +optional
	Substitute []string `json:"substitute,omitempty"`

	// PathPrefixes narrows the rule to matching request paths. Empty means all.
	// +optional
	PathPrefixes []string `json:"pathPrefixes,omitempty"`

	// Methods narrows the rule to these HTTP methods. Empty means all.
	// +optional
	Methods []string `json:"methods,omitempty"`
}

type LangfuseSpec struct {
	// +optional
	Enabled *bool `json:"enabled,omitempty"`
	// +optional
	BaseURL string `json:"baseURL,omitempty"`
	// +optional
	PublicKeyRef *SecretKeySelector `json:"publicKeyRef,omitempty"`
	// +optional
	SecretKeyRef *SecretKeySelector `json:"secretKeyRef,omitempty"`
	// Environment separates deployments inside one Langfuse project. Changing it
	// on a live agent splits its history from every trace recorded before, with
	// no way to merge the two afterwards.
	// +optional
	Environment string `json:"environment,omitempty"`
}

type MCPServerSpec struct {
	// +required
	Name string `json:"name"`
	// +kubebuilder:validation:Enum=http;sse;stdio
	// +required
	Transport string `json:"transport"`
	// +optional
	URL string `json:"url,omitempty"`
	// Command runs a stdio server inside the Brain container.
	// +optional
	Command []string `json:"command,omitempty"`
	// HeadersFrom supplies auth headers from a Secret.
	// +optional
	HeadersFrom *SecretKeySelector `json:"headersFrom,omitempty"`
}

type ManagedAgent struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`

	// spec defines the desired state of ManagedAgent
	// +required
	Spec ManagedAgentSpec `json:"spec"`

	// status defines the observed state of ManagedAgent
	// +optional
	Status ManagedAgentStatus `json:"status,omitzero"`
}

type ManagedAgentBrain struct {
	// GatewayPort is the agent gateway's port — the one contract callers use.
	// +kubebuilder:default=4099
	// +optional
	GatewayPort int32 `json:"gatewayPort,omitempty"`

	// WorkspaceFSPort serves attachment staging and the workspace file browser.
	// It is a separate process from the gateway and must be exposed for the
	// file panel and attachment upload to work at all.
	// +kubebuilder:default=8766
	// +optional
	WorkspaceFSPort int32 `json:"workspaceFSPort,omitempty"`

	// +optional
	Resources corev1.ResourceRequirements `json:"resources,omitzero"`
	// +optional
	NodeSelector map[string]string `json:"nodeSelector,omitempty"`
	// +optional
	Tolerations []corev1.Toleration `json:"tolerations,omitempty"`
	// +optional
	Affinity *corev1.Affinity `json:"affinity,omitempty"`
	// +optional
	ServiceAccountName string `json:"serviceAccountName,omitempty"`

	// ExtraEnv is passed to the Brain verbatim, secretKeyRef included. See the
	// note on ManagedAgentSpec: this is where tenant-specific configuration
	// lives until (and unless) it earns a first-class field.
	// +optional
	ExtraEnv []corev1.EnvVar `json:"extraEnv,omitempty"`

	// +optional
	ExtraEnvFrom []corev1.EnvFromSource `json:"extraEnvFrom,omitempty"`
	// +optional
	ExtraVolumes []corev1.Volume `json:"extraVolumes,omitempty"`
	// +optional
	ExtraVolumeMounts []corev1.VolumeMount `json:"extraVolumeMounts,omitempty"`
	// ExtraPorts exposes additional in-pod processes (a vendor MCP server, for
	// instance) on the Brain Service.
	// +optional
	ExtraPorts []corev1.ContainerPort `json:"extraPorts,omitempty"`
}

type ManagedAgentClassifier struct {
	// +kubebuilder:default=true
	// +optional
	Enabled *bool `json:"enabled,omitempty"`
	// +kubebuilder:validation:Enum=anthropic-messages;openai-chat
	// +optional
	Wire string `json:"wire,omitempty"`
	// +optional
	BaseURL string `json:"baseURL,omitempty"`
	// +optional
	CredentialsRef *SecretKeySelector `json:"credentialsRef,omitempty"`
	// Model must be a non-reasoning id (see ManagedAgentModel.NonReasoning).
	// +optional
	Model string `json:"model,omitempty"`
	// +optional
	MaxTokens int32 `json:"maxTokens,omitempty"`
	// +optional
	MaxContextChars int32 `json:"maxContextChars,omitempty"`
	// TimeoutSeconds must stay below any reverse proxy read timeout in front of
	// the Brain; a classifier timeout fails safe to "same topic".
	// +optional
	TimeoutSeconds int32 `json:"timeoutSeconds,omitempty"`
}

type ManagedAgentHands struct {
	// EnvRef reuses an existing SandboxEnv. The controller only probes it; it
	// writes nothing on the worker side.
	// +optional
	EnvRef *HandsEnvRef `json:"envRef,omitempty"`

	// Auto derives a SandboxEnv named "<agent>-hands" with one member pool per
	// instance type, named "<agent>-hands-<instanceType>".
	// +optional
	Auto *HandsAutoSpec `json:"auto,omitempty"`

	// External points at an E2B-compatible sandbox service this control plane
	// does not own — another AgentBox installation, or a managed offering. The
	// platform never inspects or reconciles it; the Brain simply speaks the API.
	// +optional
	External *HandsExternal `json:"external,omitempty"`

	// Binding covers how a thread is tied to a sandbox.
	// +optional
	Binding *HandsBinding `json:"binding,omitempty"`

	// E2B is the endpoint and credential the Brain uses to reach the sandbox
	// API. When omitted, the Brain falls back to in-cluster service DNS, which
	// only works on a cluster that runs the worker chart.
	// +optional
	E2B *HandsE2B `json:"e2b,omitempty"`
}

type ManagedAgentImage struct {
	// +required
	Repository string `json:"repository"`
	// +optional
	Tag string `json:"tag,omitempty"`
	// +kubebuilder:validation:Enum=Always;IfNotPresent;Never
	// +optional
	PullPolicy corev1.PullPolicy `json:"pullPolicy,omitempty"`
	// +optional
	PullSecrets []corev1.LocalObjectReference `json:"pullSecrets,omitempty"`
}

type ManagedAgentIngress struct {
	// Enabled publishes the agent. While false the shared route answers 404 for
	// this agent's name, so an agent is never reachable from outside by
	// accident — being deployed is not the same as being published.
	// +kubebuilder:default=false
	// +optional
	Enabled bool `json:"enabled,omitempty"`
}

type ManagedAgentList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []ManagedAgent `json:"items"`
}

type ManagedAgentModel struct {
	// +required
	ID string `json:"id"`
	// +optional
	Name string `json:"name,omitempty"`
	// NonReasoning marks a model eligible to back the topic classifier. A
	// reasoning model spends its completion budget on the chain of thought and
	// returns empty content, which reads as "same topic" every time.
	// +optional
	NonReasoning bool `json:"nonReasoning,omitempty"`
}

type ManagedAgentObservability struct {
	// +optional
	Langfuse *LangfuseSpec `json:"langfuse,omitempty"`
}

type ManagedAgentOwner struct {
	// +optional
	Team string `json:"team,omitempty"`
	// +optional
	User string `json:"user,omitempty"`
}

type ManagedAgentPrompt struct {
	// Inline is the prompt text.
	// +optional
	Inline string `json:"inline,omitempty"`
	// From reads the prompt from a ConfigMap key. Takes precedence over Inline.
	// +optional
	From *ConfigMapKeySelector `json:"from,omitempty"`
	// Append is added after whatever the harness's own preset contributes.
	// +optional
	Append string `json:"append,omitempty"`
}

type ManagedAgentRuntime struct {
	// Default is the harness a conversation starts under when the caller picks
	// none. Every CONFIGURED harness is served regardless — the browser has a
	// picker — so this is a default, not a restriction.
	// +kubebuilder:validation:Enum=claude-code;opencode
	// +required
	Default string `json:"default"`

	// ClaudeCode speaks the Anthropic Messages API. Anthropic does not support
	// routing Claude Code at non-Claude models, so baseURL must serve them.
	// +optional
	ClaudeCode *ClaudeCodeRuntime `json:"claudeCode,omitempty"`

	// OpenCode speaks an OpenAI-compatible API.
	// +optional
	OpenCode *OpenCodeRuntime `json:"opencode,omitempty"`
}

type ManagedAgentScenario struct {
	// Name is the identifier callers pass on /run. DNS-1123 label.
	// +required
	Name string `json:"name"`

	// +optional
	DisplayName string `json:"displayName,omitempty"`

	// Default marks the scenario used when a caller names none. Exactly one.
	// +optional
	Default bool `json:"default,omitempty"`

	// Prompt is APPENDED to spec.prompt, never substituted.
	// +optional
	Prompt *ManagedAgentPrompt `json:"prompt,omitempty"`

	// Runtime pins this scenario to one harness. Unattended flows should pin,
	// so a user switching harness in the console does not drag background
	// analysis onto an unverified model configuration.
	// +kubebuilder:validation:Enum=claude-code;opencode
	// +optional
	Runtime string `json:"runtime,omitempty"`

	// Model overrides the harness default for this scenario.
	// +optional
	Model string `json:"model,omitempty"`

	// Allow is the tool allow-list: which registered MCP servers and
	// client-side tools this scenario may see. The sandbox toolset and
	// AskUserQuestion are not listed here — they are on by default.
	//
	// Registration (spec.tools) and visibility (this field) are separate on
	// purpose, and visibility is DENY BY DEFAULT: forgetting to configure a
	// scenario must fail towards "the tool is invisible", never towards "the
	// agent can post to a chat group". Visibility is computed server-side and
	// decides which tools are registered with the harness at all — an unlisted
	// tool is absent from the model's tool list rather than rejected at call
	// time, which would burn turns and leak the tool's existence.
	// +optional
	Allow []string `json:"allow,omitempty"`

	// Disable removes individual sandbox tools (bash, read, write, edit, grep,
	// glob, apply_patch) from this scenario.
	// +optional
	Disable []string `json:"disable,omitempty"`

	// Interactive false means the agent cannot ask the user a question: its
	// prompts degrade to plain text instead of rendering a card nobody can
	// click. Unattended flows must set this false.
	// +kubebuilder:default=true
	// +optional
	Interactive *bool `json:"interactive,omitempty"`

	// SandboxEnv is injected into the sandbox at CREATE time and is immutable
	// for that sandbox's life. That is why a thread is bound to one scenario
	// when it is created and cannot switch afterwards.
	// +optional
	SandboxEnv []corev1.EnvVar `json:"sandboxEnv,omitempty"`

	// ScalingGroup routes this scenario's sandboxes to one member pool
	// (rendered as the reserved metadata key agentbox.scitix.ai/scaling-group).
	// +optional
	ScalingGroup string `json:"scalingGroup,omitempty"`

	// Image overrides the sandbox image for this scenario while still reusing
	// the same SandboxEnv and warm pool.
	// +optional
	Image string `json:"image,omitempty"`

	// Exposed false hides the scenario from the console picker and the public
	// scenario list; callers may still name it explicitly.
	// +kubebuilder:default=true
	// +optional
	Exposed *bool `json:"exposed,omitempty"`
}

type ManagedAgentSession struct {
	// +optional
	Persistence *SessionPersistence `json:"persistence,omitempty"`
	// RetentionDays prunes threads older than this. Zero means keep forever.
	// +optional
	RetentionDays int32 `json:"retentionDays,omitempty"`
}

type ManagedAgentSpec struct {
	// DisplayName is shown in the console. Defaults to metadata.name.
	// +optional
	DisplayName string `json:"displayName,omitempty"`

	// Description is free-form text for the console.
	// +optional
	Description string `json:"description,omitempty"`

	// Owner is stamped from the authenticated caller when the agent is created
	// and is not settable through the console. An agent belongs to one person,
	// not to their whole team: a teammate listing agents does not see it, and a
	// request for it is answered 404 rather than 403 — whether someone else's
	// agent exists is itself not disclosed.
	// +optional
	Owner *ManagedAgentOwner `json:"owner,omitempty"`

	// Image is the Brain image. It must ship every harness listed under
	// `runtime`, plus the sandbox daemon and the workspace-fs server.
	// +required
	Image ManagedAgentImage `json:"image"`

	// Runtime declares which harnesses this agent can serve and how each reaches
	// its model endpoint. At least one must be configured, otherwise the Brain
	// starts and reports every harness unavailable through GET /backends.
	// +required
	Runtime ManagedAgentRuntime `json:"runtime"`

	// Classifier configures the one-shot "is this a new topic?" check. It is
	// deliberately NOT part of `runtime`: reusing a harness's model would make
	// the check's cost and behaviour change whenever a user switches harness.
	// +optional
	Classifier *ManagedAgentClassifier `json:"classifier,omitempty"`

	// Prompt is the base system prompt shared by every scenario — the sandbox
	// contract (what exists in the image, what the cwd is, what gets reclaimed).
	// Scenario prompts are APPENDED to it, never substituted: a statement that
	// stops being true when the scenario changes does not belong here.
	// +optional
	Prompt *ManagedAgentPrompt `json:"prompt,omitempty"`

	// Scenarios are the agent's slices. Each bundles a prompt addendum, a tool
	// allow-list, an optional harness pin and sandbox env. Exactly one entry
	// must set `default: true`.
	// +optional
	// +listType=map
	// +listMapKey=name
	Scenarios []ManagedAgentScenario `json:"scenarios,omitempty"`

	// Tools is the registry: which MCP servers and client-side tools exist, how
	// to reach them and where their credentials live.
	//
	// Registration is not visibility. A registered tool is invisible until some
	// scenario names it in `allow`, and visibility is computed server-side into
	// the tool set the harness is given — an unlisted tool is absent from the
	// model's tool list rather than refused at call time, which would burn turns
	// and disclose that it exists.
	// +optional
	Tools *ToolPolicySpec `json:"tools,omitempty"`

	// Ingress publishes this agent outside the cluster.
	//
	// Traffic never reaches the Brain directly. The Brain authenticates nothing
	// — it takes the caller's word for which end user is asking, which is safe
	// only because it is unreachable from outside — so exposing it as-is would
	// let anyone read every tenant's threads and drive the agent's tools.
	// External callers arrive through the control-plane proxy, which checks the
	// API key and that the key's owner may use this agent before forwarding.
	// +optional
	Ingress *ManagedAgentIngress `json:"ingress,omitempty"`

	// Hands declares sandbox supply: reference an existing SandboxEnv, derive
	// one, or point at an external service. Exactly one branch must be set.
	// +required
	Hands ManagedAgentHands `json:"hands"`

	// Session covers thread persistence.
	// +optional
	Session *ManagedAgentSession `json:"session,omitempty"`

	// Observability is Langfuse today.
	// +optional
	Observability *ManagedAgentObservability `json:"observability,omitempty"`

	// Docs is operator-supplied Markdown shown as the agent's landing tab in the
	// console: how to reach this agent, what its scenarios mean, which tools they
	// expose. It travels with the object rather than being compiled into the
	// console so a deployment can write it in its own language and keep it
	// accurate for its own conventions.
	// +optional
	Docs string `json:"docs,omitempty"`

	// Brain tunes the Deployment. Replicas are always 1 with strategy Recreate:
	// the session-to-sandbox map lives in the daemon's memory and sandbox
	// handles cannot be recovered across processes (the E2B layer answers
	// `Sandbox.connect` with "not supported in AgentBox"), so a second replica
	// would silently create a second sandbox for the same thread.
	// +optional
	Brain *ManagedAgentBrain `json:"brain,omitempty"`
}

type ManagedAgentStatus struct {
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Phase is a coarse rollup: Pending, Provisioning, Ready, Degraded, Failed.
	// +optional
	Phase string `json:"phase,omitempty"`

	// Endpoint is the in-cluster URL of the agent gateway. It reaches the Brain
	// directly and is therefore unauthenticated — only ever hand it to callers
	// already inside the cluster.
	// +optional
	Endpoint string `json:"endpoint,omitempty"`

	// PublicURL is the address external callers use, set only while the agent
	// is published. Unlike Endpoint it goes through the authenticating proxy,
	// so a caller needs an API key whose owner may use this agent.
	// +optional
	PublicURL string `json:"publicURL,omitempty"`

	// Hands reports the resolved sandbox supply.
	// +optional
	Hands *ResolvedHands `json:"hands,omitempty"`

	// Backends mirrors the Brain's own view of each harness, including why one
	// is unavailable. A harness failing preflight is reported here rather than
	// taking the pod down — a bad model credential must not stop the other
	// processes in the pod from serving.
	// +optional
	Backends []BackendStatus `json:"backends,omitempty"`

	// Scenarios lists the scenario names currently served.
	// +optional
	Scenarios []string `json:"scenarios,omitempty"`

	// +optional
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type MemberMetadata struct {
	// Labels are the candidate Pool's metadata.labels post-PreCreatePool.
	// +optional
	Labels map[string]string `json:"labels,omitempty"`

	// Annotations are the candidate Pool's metadata.annotations post-PreCreatePool.
	// +optional
	Annotations map[string]string `json:"annotations,omitempty"`
}

type ObservedMemberState string

type OpenCodeRuntime struct {
	// Enabled withdraws the harness from the picker AND stops the entrypoint
	// from launching its server — one value drives both, so the picker can never
	// offer a harness whose server nobody started.
	// +kubebuilder:default=true
	// +optional
	Enabled *bool `json:"enabled,omitempty"`

	// Port is the loopback port for `opencode serve`.
	// +kubebuilder:default=4096
	// +optional
	Port int32 `json:"port,omitempty"`

	// BaseURL is the OpenAI-compatible endpoint this harness may reach.
	// +optional
	BaseURL string `json:"baseURL,omitempty"`

	// CredentialsRef supplies the provider API key. The console collects the key
	// itself and the platform materialises this reference; it can also be set
	// directly to an existing Secret.
	// +optional
	CredentialsRef *SecretKeySelector `json:"credentialsRef,omitempty"`

	// Models is the exact in-composer dropdown for this harness.
	// +optional
	Models []ManagedAgentModel `json:"models,omitempty"`

	// +optional
	DefaultModel string `json:"defaultModel,omitempty"`

	// ProviderID names the single provider in the generated config. It is not
	// cosmetic: every model is addressed as "<providerID>/<model-id>", so this
	// string is part of the model identity the composer sends back. Changing it
	// on a live agent invalidates whatever model ids callers have stored.
	// +kubebuilder:default=platform
	// +optional
	ProviderID string `json:"providerID,omitempty"`

	// ProviderName is the provider's display label in the model picker.
	// +optional
	ProviderName string `json:"providerName,omitempty"`

	// Overlay is harness configuration the platform does not model: plugins,
	// telemetry switches, tool output limits. It is merged *underneath* the
	// generated keys, so an overlay cannot widen the provider allow-list,
	// repoint the endpoint, or re-enable a gated tool — the keys that decide
	// where data goes stay generated.
	//
	// This is the seam that keeps the CRD from growing a field per harness
	// knob. Use ConfigSecretRef instead only when you want no generated config
	// at all.
	// +optional
	Overlay *apiextensionsv1.JSON `json:"overlay,omitempty"`

	// ConfigSecretRef brings your own opencode.json instead of the generated
	// one. It bypasses the provider allow-list above, so a hand-managed config
	// must set `enabled_providers` itself.
	// +optional
	ConfigSecretRef *SecretKeySelector `json:"configSecretRef,omitempty"`
}

type PodCreationImagePolicy string

type PoolAutoScalingStatus struct {
	// LastScaleUpTime is the wall-clock time of the most recent
	// scale-up that actually increased spec.replicas (the probe
	// accepted at least one additional replica). Drives the success
	// cooldown gate (scaleUpPolicy.cooldownSeconds).
	// +optional
	LastScaleUpTime *metav1.Time `json:"lastScaleUpTime,omitempty"`

	// LastScaleDownTime is the wall-clock time of the most recent
	// successful scale-down (spec.replicas decreased) on this Pool. Drives
	// scaleDownPolicy.stabilizationSeconds.
	// +optional
	LastScaleDownTime *metav1.Time `json:"lastScaleDownTime,omitempty"`

	// IdleZeroSince is the wall-clock time at which this Pool's idle
	// replica count first dropped to zero in the current continuous-zero
	// window. Cleared the instant idle > 0 is observed. Drives the
	// proactive scaleUpPolicy.idleThresholdSeconds trigger.
	// +optional
	IdleZeroSince *metav1.Time `json:"idleZeroSince,omitempty"`

	// LastScaleUpAttemptTime records when the autoscaler last invoked
	// the admission probe for a scale-up, regardless of whether the
	// probe accepted the target. Together with LastScaleUpAttemptResult
	// and the group's SaturationCooldownSeconds it drives the saturation
	// cooldown: when the last attempt was Insufficient / JustRight /
	// Failed, the autoscaler and router treat the Pool as saturated
	// until SaturationCooldownSeconds has elapsed past this timestamp.
	// +optional
	LastScaleUpAttemptTime *metav1.Time `json:"lastScaleUpAttemptTime,omitempty"`

	// LastScaleUpAttemptResult records the outcome of the most recent
	// scale-up admission probe. Empty before the first attempt; one of
	// the PoolScaleUpAttemptResult enum values otherwise.
	// +optional
	LastScaleUpAttemptResult PoolScaleUpAttemptResult `json:"lastScaleUpAttemptResult,omitempty"`

	// ScaleUpErrorMessage is a short single-line description of the most
	// recent non-Enough scale-up result, suitable for surfacing to the
	// dashboard. Empty when LastScaleUpAttemptResult is Enough.
	// +optional
	ScaleUpErrorMessage string `json:"scaleUpErrorMessage,omitempty"`

	// ObservedGeneration is the metadata.generation observed when the
	// autoscaler last wrote this block. Clients may use it to confirm the
	// status is current with respect to the spec they care about.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
}

type PoolScaleDownPolicy struct {
	// IdleTimeoutSeconds is the minimum duration (in seconds) a Pod must remain
	// in Idle state before it becomes a candidate for scale-down.
	// Defaults to 300 (5 minutes).
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:default=300
	IdleTimeoutSeconds int32 `json:"idleTimeoutSeconds,omitempty"`

	// StabilizationSeconds is the minimum number of seconds between two consecutive
	// scale-down events. Prevents thrashing when load fluctuates around the threshold.
	// Defaults to 60.
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:default=60
	StabilizationSeconds int32 `json:"stabilizationSeconds,omitempty"`

	// ProtectionWindowSeconds is the time window after a Pod is marked for
	// scale-down (via the scale-down-protected annotation) during which a new
	// Create Sandbox request can still claim it, cancelling the scale-down intent.
	// Defaults to 10.
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:default=10
	ProtectionWindowSeconds int32 `json:"protectionWindowSeconds,omitempty"`
}

type PoolScaleUpAttemptResult string

type PoolScaleUpMode string

type PoolScaleUpPolicy struct {
	// Mode controls how aggressively the pool grows on each scale-up decision.
	//   - Conservative: +1 per decision
	//   - Default:      +max(1, ceil(currentReplicas/2))
	//   - Aggressive:   scale to min(currentReplicas*2, maxReplicas)
	// Defaults to Default.
	// +optional
	// +kubebuilder:validation:Enum=Conservative;Default;Aggressive
	// +kubebuilder:default=Default
	Mode PoolScaleUpMode `json:"mode,omitempty"`

	// CooldownSeconds is the minimum number of seconds between two consecutive
	// scale-up events. Prevents scale-up storms when many requests arrive simultaneously.
	// Defaults to 30.
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:default=30
	CooldownSeconds int32 `json:"cooldownSeconds,omitempty"`

	// IdleThresholdSeconds triggers a proactive scale-up when idleReplicas == 0
	// has persisted for this many seconds. Set to 0 to disable proactive scale-up.
	// Defaults to 30.
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:default=30
	IdleThresholdSeconds int32 `json:"idleThresholdSeconds,omitempty"`

	// IdleZeroQuietWindowSeconds suppresses the proactive idleZero
	// scale-up trigger when no Sandbox.Create request has been observed
	// for this Pool within the most recent window. Concretely: if
	// `now - LastSandboxCreateTime > idleZeroQuietWindowSeconds` AND
	// `IdleThresholdSeconds` has elapsed since `idleReplicas` last hit
	// zero, the autoscaler will NOT fire a proactive scale-up. Reactive
	// scale-ups (queue length > 0 with no idle Pod) ignore this window
	// — a real waiter always wins. Set to 0 to disable the quiet-window
	// gate so proactive scale-up fires the moment IdleThresholdSeconds
	// elapses.
	// Defaults to 300 (5 minutes).
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:default=300
	IdleZeroQuietWindowSeconds int32 `json:"idleZeroQuietWindowSeconds,omitempty"`

	// SaturationCooldownSeconds is the duration the Env autoscaler keeps
	// a member marked saturated after a probe returned InsufficientResources
	// (or InvalidSpec). Subsequent reconciles skip the member's expensive
	// PreUpdatePool probe until the cooldown elapses; the router also
	// deprioritises saturated members. Defaults to 60.
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:default=60
	SaturationCooldownSeconds int32 `json:"saturationCooldownSeconds,omitempty"`
}

type ResolvedHands struct {
	// +optional
	ClusterID string `json:"clusterID,omitempty"`
	// +optional
	EnvName string `json:"envName,omitempty"`
	// +optional
	Pools []string `json:"pools,omitempty"`
	// +optional
	Ready bool `json:"ready,omitempty"`
}

type SandboxEnv struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`

	// spec defines the desired state of SandboxEnv
	// +required
	Spec SandboxEnvSpec `json:"spec"`

	// status defines the observed state of SandboxEnv
	// +optional
	Status SandboxEnvStatus `json:"status,omitzero"`
}

type SandboxEnvDefaults struct {
	// InstanceType references an entry in the cluster-wide InstanceType catalog.
	// May be empty when the Env was migrated from a legacy SandboxPool that did
	// not carry an InstanceType label — in that case members use InlineResources.
	// +optional
	InstanceType string `json:"instanceType,omitempty"`

	// Multiplier scales the InstanceType's base resources. Must fall within the
	// InstanceType's declared [min, max] range; validated by the Env Controller.
	// +optional
	// +kubebuilder:validation:Minimum=1
	Multiplier int32 `json:"multiplier,omitempty"`
}

type SandboxEnvList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []SandboxEnv `json:"items"`
}

type SandboxEnvMode string

type SandboxEnvSpec struct {
	// TemplateRef binds this Env to exactly one SandboxTemplate (runtime). All
	// member Pools must reference the same Template.
	// +required
	TemplateRef SandboxEnvTemplateRef `json:"templateRef"`

	// Mode selects between WarmPool (predefined member Pools) and OnDemandJob
	// (per-request SandboxJob).
	// +required
	// +kubebuilder:default=WarmPool
	Mode SandboxEnvMode `json:"mode"`

	// Defaults supplies the InstanceType and multiplier used when a Sandbox.create
	// request does not specify them explicitly. Strongly recommended.
	// +optional
	Defaults *SandboxEnvDefaults `json:"defaults,omitempty"`

	// Clusters is the per-cluster member list. Each segment is owned exclusively
	// by the Worker whose ClusterID matches; foreign segments are read-only to
	// other Workers. Hub merges contributions from all Workers in Phase 2.
	// +optional
	// +listType=map
	// +listMapKey=clusterID
	Clusters []EnvClusterSpec `json:"clusters,omitempty"`

	// Autoscaling configures the Env-level autoscaler. When nil or
	// Autoscaling.Enabled=false, member Pool replicas are managed manually.
	// +optional
	Autoscaling *EnvAutoscalingSpec `json:"autoscaling,omitempty"`

	// Overrides carries the Env-wide overrides that uniformly replace
	// fields of the referenced SandboxTemplate for every member Pool.
	// Per-Pool variations (resource multiplier, replicas, plugin metadata
	// like quota URLs) live on each EnvClusterMember instead.
	// +optional
	Overrides *EnvOverridesSpec `json:"overrides,omitempty"`
}

type SandboxEnvStatus struct {
	// Conditions surfaces high-level Env health signals (Ready,
	// TemplateConsistent, AutoscalingActive, …).
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// Clusters carries the per-cluster observed state. Worker writes only the
	// segment with IsLocal=true; other segments are populated by Hub Sync.
	// +optional
	// +listType=map
	// +listMapKey=clusterID
	Clusters []EnvClusterStatus `json:"clusters,omitempty"`

	// ScalingGroups aggregates idle/running counts per scalingGroup across all
	// members (across clusters when remote segments are populated by Sync).
	// +optional
	// +listType=map
	// +listMapKey=name
	ScalingGroups []EnvScalingGroupStatus `json:"scalingGroups,omitempty"`

	// MemberCount is the total number of member Pools, summed across every
	// cluster segment. It exists because printer columns cannot evaluate the
	// nested clusters[].members[] array. Today only the local segment is
	// observed, so it equals the local member count; once foreign segments are
	// populated it reflects the cross-cluster total.
	// +optional
	MemberCount int32 `json:"memberCount,omitempty"`

	// DesiredReplicas, RunningReplicas, IdleReplicas are env-wide rollups of
	// the per-member counts, summed across every observed member. They back
	// the printer columns (which cannot sum nested arrays) and give a single
	// at-a-glance view of capacity vs. utilisation.
	// +optional
	DesiredReplicas int32 `json:"desiredReplicas,omitempty"`
	// +optional
	RunningReplicas int32 `json:"runningReplicas,omitempty"`
	// +optional
	IdleReplicas int32 `json:"idleReplicas,omitempty"`
}

type SandboxEnvTemplateRef struct {
	// Name of the SandboxTemplate (cluster-scoped).
	// +required
	Name string `json:"name"`

	// Version records the SandboxTemplate spec.version this Env was created
	// against.
	//
	// Legacy: it does not pin anything. A SandboxTemplate is a single mutable
	// cluster-scoped object — there is no version history and no way to
	// resolve an older spec.version — so every consumer resolves the Template
	// by Name alone and members always converge onto its current body. The
	// version actually in effect is reported per member in
	// status.clusters[].observedMembers[].templateVersion; read that instead
	// of this field. Retained so existing objects and manifests keep
	// round-tripping; real version pinning needs immutable per-version
	// Template objects first.
	// +optional
	Version string `json:"version,omitempty"`
}

type SandboxNetworkPolicy struct {
	// DisableEgress blocks all outbound traffic (DNS still resolves so lookups
	// do not hang). Takes precedence over Egress. A quick "no internet" switch.
	// +optional
	DisableEgress bool `json:"disableEgress,omitempty"`

	// Egress is the allowlist. When DisableEgress is false and Egress is nil,
	// egress is unrestricted — including private ranges, see
	// AllowPrivateNetworks.
	// +optional
	Egress *EgressRules `json:"egress,omitempty"`

	// AllowPrivateNetworks disables the default deny of private / link-local /
	// cloud-metadata ranges (RFC1918, 169.254.0.0/16, etc.) for a policy that
	// declares filtering. Default false — the anti-SSRF baseline stays on.
	// Enable only for trusted intra-cluster access.
	//
	// Implied when Egress is nil and DisableEgress is false: a policy that
	// filters nothing (SecretInjection-only, say) must not be stricter than
	// having no policy at all, where no sidecar exists and private ranges are
	// reachable. To allow every host but keep the baseline, declare
	// Egress with AllowedDomains ["*"] and AllowedCIDRs ["0.0.0.0/0"] instead.
	// +optional
	AllowPrivateNetworks bool `json:"allowPrivateNetworks,omitempty"`

	// SecretInjection brokers credentials on the way out: the sidecar terminates
	// TLS for the listed hosts and adds (or substitutes) the configured headers,
	// so the sandbox can use a credential without ever being able to read it.
	// nil disables it.
	//
	// Setting this alone (with Egress nil) is valid and means "inject, but do
	// not filter": the sidecar is still injected — which is what makes the
	// interception possible — while egress stays unrestricted, private ranges
	// included, so enabling injection never narrows what the sandbox can reach.
	//
	// Declarable only on a SandboxEnv. Sandbox-create requests carrying it are
	// rejected, because a credential travelling through a create request would
	// re-introduce exactly the exposure this feature removes.
	// +optional
	SecretInjection *SecretInjection `json:"secretInjection,omitempty"`
}

type SandboxPool struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`

	// spec defines the desired state of SandboxPool
	// +required
	Spec SandboxPoolSpec `json:"spec"`

	// status defines the observed state of SandboxPool
	// +optional
	Status SandboxPoolStatus `json:"status,omitzero"`
}

type SandboxPoolList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []SandboxPool `json:"items"`
}

type SandboxPoolPhase string

type SandboxPoolSpec struct {

	// Replicas is the total desired number of Pods (Idle + Running + Starting + Stopping).
	// Adjusted by the SandboxEnv autoscaler (when the Pool is owned by an Env) or
	// directly by the operator for unmanaged Pools.
	// +kubebuilder:validation:Minimum=0
	Replicas int32 `json:"replicas"`

	// TemplateName references a cluster-scoped SandboxTemplate to use as the base
	// configuration. When set, the template's EmbeddedSandboxTemplate is copied at
	// creation time. Inline fields in SandboxPoolSpec override template fields.
	// +optional
	TemplateName string `json:"templateName,omitempty"`

	// DefaultStartupTimeout is the default startup timeout applied to sandbox create
	// requests in this pool when the CreateSandbox request does not specify a startupTimeout.
	// It also serves as the upper bound for the Starting phase: the controller deletes any pod
	// that has been in Starting phase longer than this value.
	//
	// When nil, the controller does not enforce an upper bound on the Starting phase
	// (pods with a per-pod agentbox.navix.sh/startup-timeout annotation are still cleaned up),
	// and create requests without an explicit startupTimeout use the internal default (2 minutes).
	// +optional
	DefaultStartupTimeout *metav1.Duration `json:"defaultStartupTimeout,omitempty"`

	// DefaultIdleTimeout is the default idle timeout applied to sandboxes created
	// in this pool when the CreateSandbox request does not specify an idleTimeout.
	// If nil, sandboxes have no idle timeout by default (they run until explicitly released).
	// +optional
	DefaultIdleTimeout *metav1.Duration `json:"defaultIdleTimeout,omitempty"`

	// PodCreationImagePolicy controls which image newly created Pods start with,
	// regardless of whether replicas are increased manually or by autoscaling.
	//   - PoolDefaultImage: preserve template container image (current behavior)
	//   - IdleImage:        override the first container image with spec.idleImage
	// +optional
	// +kubebuilder:validation:Enum=PoolDefaultImage;IdleImage
	// +kubebuilder:default=IdleImage
	PodCreationImagePolicy PodCreationImagePolicy `json:"podCreationImagePolicy,omitempty"`

	// NetworkPolicy, when set, enables sandbox egress filtering for Pods in this
	// Pool: the operator injects a transparent filter sidecar. For Env-owned
	// Pools this is projected from the Env's overrides.networkPolicy and serves
	// as the default ruleset; per-sandbox create requests may override it.
	// +optional
	NetworkPolicy *SandboxNetworkPolicy `json:"networkPolicy,omitempty"`

	// MaxUnavailable bounds how many of this Pool's desired idle Pods may be
	// unavailable at once while it rolls stale idle Pods onto a new revision
	// (see status.updateRevision). Absolute number or percentage of replicas
	// (e.g. "20%"), rounded down and floored at 1. For Env-owned Pools this is
	// projected from the Env's (member/overrides) updateStrategy; nil disables
	// rollout throttling and is treated as "20%".
	// +optional
	// +kubebuilder:validation:XIntOrString
	MaxUnavailable *intstr.IntOrString `json:"maxUnavailable,omitempty"`

	EmbeddedSandboxTemplate `json:",inline"`
}

type SandboxPoolStatus struct {

	// Phase is a high-level summary of the pool's current state.
	// Possible values: Pending, Ready, ScalingUp, ScalingDown, Degraded, Terminating.
	//
	// Phase is determined by the following priority rules:
	//   - Terminating: DeletionTimestamp is set
	//   - Pending:     spec.replicas == 0 and no pods exist
	//   - ScalingUp:   current pod count < spec.replicas
	//   - ScalingDown: current pod count > spec.replicas (may persist while running pods cannot be deleted)
	//   - Degraded:    replica count is stable but unavailableIdleReplicas > 0 or failedReplicas > 0
	//   - Ready:       all replicas present and all pods are healthy
	// +optional
	Phase SandboxPoolPhase `json:"phase,omitempty"`

	// IdleReplicas is the number of Pods in idle state
	// +optional
	IdleReplicas int32 `json:"idleReplicas,omitempty"`

	// UnavailableIdleReplicas is the number of Pods in idle phase whose Kubernetes PodReady
	// condition is not True (e.g. Pending, CrashLoopBackOff, ErrImagePull).
	// These Pods are counted in IdleReplicas but cannot accept sandbox requests.
	// A non-zero value causes the pool to enter the Degraded phase.
	// +optional
	UnavailableIdleReplicas int32 `json:"unavailableIdleReplicas,omitempty"`

	// RunningReplicas is the number of Pods in running state
	// +optional
	RunningReplicas int32 `json:"runningReplicas,omitempty"`

	// StartingReplicas is the number of Pods being activated (Idle → Running)
	// +optional
	StartingReplicas int32 `json:"startingReplicas,omitempty"`

	// StoppingReplicas is the number of Pods being recycled (Running → Idle)
	// +optional
	StoppingReplicas int32 `json:"stoppingReplicas,omitempty"`

	// FailedReplicas is the number of Pods in failed state
	// +optional
	FailedReplicas int32 `json:"failedReplicas,omitempty"`

	// UpdateRevision is the target revision hash of the current Pool template
	// (spec.template.metadata.labels[agentbox.navix.sh/template-hash]). Idle
	// Pods whose own hash differs are stale and get rolled onto this revision.
	// +optional
	UpdateRevision string `json:"updateRevision,omitempty"`

	// CurrentRevision is the revision hash all Pods currently share. It equals
	// UpdateRevision once a rollout has converged, and is empty while Pods
	// straddle multiple revisions (rollout in progress).
	// +optional
	CurrentRevision string `json:"currentRevision,omitempty"`

	// UpdatedReplicas is the number of Pods already at UpdateRevision.
	// +optional
	UpdatedReplicas int32 `json:"updatedReplicas,omitempty"`

	// PendingRequests is the throttled mirror of the in-process PoolScheduler
	// claim queue depth. Patched every ~3 s when the queue length changes by
	// at least 20 % or crosses the 0/>0 boundary. Used by Dashboard for
	// real-time backlog observability; the Env autoscaler reads the live
	// in-process Snapshot instead and does not depend on this field.
	// +optional
	PendingRequests int32 `json:"pendingRequests,omitempty"`

	// Selector is the label selector string used to identify Pods managed by this Pool.
	// Deprecated: Use LabelSelector for structured access or PhaseSelectors for per-phase filtering.
	// This field is retained for kubectl scale / HPA compatibility (subresource:scale selectorpath).
	// +optional
	Selector string `json:"selector,omitempty"`

	// LabelSelector is the structured label selector matching all Pods managed by this Pool.
	// Equivalent to the Selector field but in structured metav1.LabelSelector form.
	// +optional
	LabelSelector *metav1.LabelSelector `json:"labelSelector,omitempty"`

	// PhaseSelectors contains pre-computed label selector strings for filtering Pods by phase,
	// suitable for direct use with `kubectl get pods -l <selector>`.
	// Keys: "all", "idle", "running", "starting", "stopping", "failed".
	// Example: kubectl get pods -l <phaseSelectors.running>
	// +optional
	PhaseSelectors map[string]string `json:"phaseSelectors,omitempty"`

	// conditions represent the current state of the SandboxPool resource.
	// Each condition has a unique type and reflects the status of a specific aspect of the resource.
	//
	// Standard condition types:
	// - "Available":  True when healthy idle pods are available to accept new sandbox requests.
	// - "Scaling":    True when the pool is actively scaling up or down.
	// - "Degraded":   True when unavailable idle pods or failed pods are present.
	//
	// The status of each condition is one of True, False, or Unknown.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// AutoScaling persists the Pool autoscaler's decision-time bookkeeping
	// (last scale-up/down timestamps, idle-zero window start, saturation
	// cooldown, last probe outcome). The Pool reconciler is the only writer.
	// Nil when autoscaling is disabled on this Pool's owning Env group.
	// +optional
	AutoScaling *PoolAutoScalingStatus `json:"autoscaling,omitempty"`
}

type SandboxReservationSpec struct {
	PriorityClassName string              `json:"priorityClassName,omitempty"`
	ReplicaQuota      corev1.ResourceList `json:"replicaQuota"`
}

type SandboxRuntimeSpec struct {
	// Name specifies the name of the runtime to use for the sandbox pods.
	// Supported values are "e2b", "swerex", "aiosanbdox", etc.
	Name string `json:"name"`

	// Port specifies the port number that the runtime should listen on for incoming connections.
	// +optional
	Port *int32 `json:"port,omitempty"`

	// Protocol for port. Must be UDP, TCP, or SCTP.
	// Defaults to "TCP".
	// +optional
	// +default="TCP"
	Protocol *corev1.Protocol `json:"protocol,omitempty"`

	// Description is a human-readable description of this runtime.
	// +optional
	Description string `json:"description,omitempty"`

	// LogDir is the path to the runtime's log file inside the container.
	// When set, the GetLogs API can retrieve runtime logs via file read.
	// Example: "/tmp/envd.log"
	// +optional
	LogDir string `json:"logDir,omitempty"`

	// ReadinessProbe defines the readiness check configuration for the runtime.
	// +optional
	ReadinessProbe *corev1.Probe `json:"readinessProbe,omitempty"`

	// Config contains runtime-specific configuration parameters.
	// The content and structure of this field depend on the runtime type.
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Schemaless
	// +optional
	Config *runtime.RawExtension `json:"config,omitempty"`
}

type SandboxStatusDetail struct {
	// Reason is a machine-readable cause, e.g. "Pulling", "ImagePullBackOff",
	// "ErrImagePull", "CrashLoopBackOff", "OOMKilled", "PodFailed".
	Reason string `json:"reason"`
	// Message is a human-readable description of the current state.
	Message string `json:"message"`
	// LastUpdatedTime is the RFC3339 timestamp when this record was last written.
	LastUpdatedTime string `json:"lastUpdatedTime"`
}

type SandboxStopReason string

type SandboxTemplate struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`

	// spec defines the desired state of SandboxTemplate
	// +required
	Spec SandboxTemplateSpec `json:"spec"`

	// status defines the observed state of SandboxTemplate
	// +optional
	Status SandboxTemplateStatus `json:"status,omitzero"`
}

type SandboxTemplateList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []SandboxTemplate `json:"items"`
}

type SandboxTemplateSpec struct {
	EmbeddedSandboxTemplate `json:",inline"`

	// Version is an optional semantic version string for this template (e.g. "v1.2.0").
	// +optional
	Version string `json:"version,omitempty"`

	// Description is a human-readable description of this template.
	// +optional
	Description string `json:"description,omitempty"`

	// Visibility controls which tenants can see this template.
	// When nil or Rules is empty, the template is public (visible to all).
	// +optional
	Visibility *TemplateVisibility `json:"visibility,omitempty"`
}

type SandboxTemplateStatus struct {

	// conditions represent the current state of the SandboxTemplate resource.
	// Each condition has a unique type and reflects the status of a specific aspect of the resource.
	//
	// Standard condition types include:
	// - "Available": the resource is fully functional
	// - "Progressing": the resource is being created or updated
	// - "Degraded": the resource failed to reach or maintain its desired state
	//
	// The status of each condition is one of True, False, or Unknown.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type SecretInjection struct {
	// Credentials are the named secrets rules may reference.
	// +optional
	Credentials []InjectedCredential `json:"credentials,omitempty"`

	// Rules declare what to inject, per host.
	// +optional
	Rules []InjectionRule `json:"rules,omitempty"`

	// CACertTTL bounds the lifetime of the per-sandbox CA minted for TLS
	// interception. Defaults to 24h.
	// +optional
	CACertTTL *metav1.Duration `json:"caCertTTL,omitempty"`
}

type SecretKeyRef struct {
	Name string `json:"name"`
	Key  string `json:"key"`
}

type SecretKeySelector struct {
	// +required
	Name string `json:"name"`
	// +required
	Key string `json:"key"`
}

type SessionPersistence struct {
	// Enabled false uses an emptyDir — history is lost on restart.
	// +kubebuilder:default=false
	// +optional
	Enabled *bool `json:"enabled,omitempty"`
	// ExistingClaim mounts a claim this controller does not manage.
	// +optional
	ExistingClaim string `json:"existingClaim,omitempty"`
	// +optional
	Size *resource.Quantity `json:"size,omitempty"`
	// +optional
	StorageClass string `json:"storageClass,omitempty"`
}

type TemplateVisibility struct {
	// Rules is the list of visibility rules.
	// +optional
	Rules []TemplateVisibilityRule `json:"rules,omitempty"`
}

type TemplateVisibilityRule struct {
	// Team specifies the team that can see the template.
	// Empty means any team.
	// +optional
	Team string `json:"team,omitempty"`

	// Users specifies the users that can see the template.
	// Empty means any user.
	// +optional
	Users []string `json:"users,omitempty"`
}

type ToolApproval struct {
	// Pattern matches a tool name; a trailing "*" matches a prefix.
	// +required
	Pattern string `json:"pattern"`
	// +kubebuilder:validation:Enum=allow;ask;deny
	// +required
	Action string `json:"action"`
	// Prompt is shown to whoever is asked to approve.
	// +optional
	Prompt string `json:"prompt,omitempty"`
}

type ToolPolicySpec struct {
	// MCP servers reachable by the harness.
	// +optional
	// +listType=map
	// +listMapKey=name
	MCP []MCPServerSpec `json:"mcp,omitempty"`

	// ClientSide tools are executed by the CALLER, not by the sandbox: the
	// platform only forwards the call and waits for a result. This is how an
	// agent drives its caller's own surface — navigating a page, opening a
	// panel — which no hosted runtime could do on the caller's behalf.
	// +optional
	// +listType=map
	// +listMapKey=name
	ClientSide []ClientToolSpec `json:"clientSide,omitempty"`

	// Approval gates individual tools behind a human decision. Patterns are
	// matched in order and the first hit wins; anything unmatched is allowed.
	// +optional
	Approval []ToolApproval `json:"approval,omitempty"`
}