v1alpha1

type AgentCapability struct {
	// ID uniquely identifies this capability. Used for exact matching.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	ID string `json:"id"`
	// Description explains what the capability does.
	// +optional
	Description string `json:"description,omitempty"`
	// Tags for coarse-grained filtering. A lookup matches agents that declare ALL listed tags.
	// +optional
	Tags []string `json:"tags,omitempty"`
	// InputSchema is a JSON Schema string (documentation only in v1).
	// +optional
	InputSchema string `json:"inputSchema,omitempty"`
	// OutputSchema is a JSON Schema string (documentation only in v1).
	// +optional
	OutputSchema string `json:"outputSchema,omitempty"`
	// ExposeMCP makes this capability callable as an MCP tool via the ark MCP gateway.
	// When true, the operator registers this capability as a named tool at the gateway
	// endpoint for this agent. Requires the MCP gateway to be enabled in the operator.
	// +kubebuilder:default=false
	// +optional
	ExposeMCP bool `json:"exposeMCP,omitempty"`
}

type AgentFleetEntry struct {
	// Name is the ArkAgent name.
	Name string `json:"name"`
	// Model is the LLM model this agent is configured to use.
	Model string `json:"model"`
	// ReadyReplicas is the number of agent pods currently ready.
	ReadyReplicas int32 `json:"readyReplicas"`
	// DailyTokens is the rolling 24h token usage copied from ArkAgent.status.
	// +optional
	DailyTokens int64 `json:"dailyTokens,omitempty"`
	// Capabilities lists the capability IDs this agent contributes to the index.
	// +optional
	Capabilities []string `json:"capabilities,omitempty"`
}

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

	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// +required
	Spec ArkAgentSpec `json:"spec"`

	// +optional
	Status ArkAgentStatus `json:"status,omitempty"`
}

type ArkAgentAutoscaling struct {
	// Enabled turns on KEDA-based autoscaling. When true a ScaledObject is
	// created and spec.replicas acts as the minimum replica floor.
	// +optional
	Enabled bool `json:"enabled,omitempty"`

	// MinReplicas is the minimum replica count (idle floor).
	// +kubebuilder:default=1
	// +kubebuilder:validation:Minimum=0
	// +optional
	MinReplicas *int32 `json:"minReplicas,omitempty"`

	// MaxReplicas is the maximum replica count.
	// +kubebuilder:default=10
	// +kubebuilder:validation:Minimum=1
	// +optional
	MaxReplicas *int32 `json:"maxReplicas,omitempty"`

	// TargetPendingTasks is the number of pending queue entries per replica
	// that KEDA uses as the scale trigger. Scale-up fires when pending tasks
	// exceed this threshold.
	// +kubebuilder:default=5
	// +kubebuilder:validation:Minimum=1
	// +optional
	TargetPendingTasks *int32 `json:"targetPendingTasks,omitempty"`
}

type ArkAgentList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []ArkAgent `json:"items"`
}

type ArkAgentMCPStatus struct {
	// Name matches MCPServerSpec.name.
	Name string `json:"name"`
	// URL is the MCP server endpoint that was probed.
	URL string `json:"url"`
	// Healthy is true when the last probe received a non-5xx HTTP response.
	Healthy bool `json:"healthy"`
	// Message holds the error detail when Healthy is false.
	// +optional
	Message string `json:"message,omitempty"`
	// LastCheck is when the probe was last run.
	// +optional
	LastCheck *metav1.Time `json:"lastCheck,omitempty"`
}

type ArkAgentNetworkPolicy struct {
	// Mode controls how the NetworkPolicy is generated.
	// +kubebuilder:default=default
	// +kubebuilder:validation:Enum=default;strict;disabled
	Mode NetworkPolicyMode `json:"mode"`
}

type ArkAgentSpec struct {
	// Replicas is the number of agent instances to run.
	// +kubebuilder:default=1
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:Maximum=50
	Replicas *int32 `json:"replicas,omitempty"`

	// Model is the LLM model ID (e.g. "claude-sonnet-4-20250514").
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Model string `json:"model"`

	// SystemPrompt is the inline system message injected into every agent call.
	// For long or frequently-iterated prompts, prefer systemPromptRef instead.
	// +optional
	SystemPrompt string `json:"systemPrompt,omitempty"`

	// SystemPromptRef references a ConfigMap or Secret key whose content is used
	// as the system prompt. Takes precedence over systemPrompt when both are set.
	// Updating the referenced ConfigMap or Secret triggers an automatic rolling
	// restart of agent pods.
	// +optional
	SystemPromptRef *SystemPromptSource `json:"systemPromptRef,omitempty"`

	// MCPServers lists the MCP tool servers available to this agent.
	MCPServers []MCPServerSpec `json:"mcpServers,omitempty"`

	// Limits constrains agent resource usage.
	Limits *ArkonisLimits `json:"limits,omitempty"`

	// LivenessProbe defines how agent health is evaluated.
	LivenessProbe *ArkonisProbe `json:"livenessProbe,omitempty"`

	// SettingsRefs references one or more ArkSettings objects whose fragments are composed
	// into this agent's system prompt, in list order. When the same fragment name appears in
	// multiple settings, the last occurrence wins. Temperature, outputFormat, and memoryBackend
	// are also merged with last-wins semantics.
	// Takes precedence over the deprecated ConfigRef when both are set.
	// +optional
	SettingsRefs []LocalObjectReference `json:"settingsRefs,omitempty"`

	// ConfigRef is deprecated. Use SettingsRefs instead.
	// +optional
	ConfigRef *LocalObjectReference `json:"configRef,omitempty"`

	// MemoryRef optionally references an ArkMemory that defines the persistent
	// memory backend for agent instances. When set, the operator injects memory
	// connection details as environment variables into agent pods.
	MemoryRef *LocalObjectReference `json:"memoryRef,omitempty"`

	// Tools lists inline HTTP webhook tools available to agent pods without an external MCP server.
	// The operator serialises these as JSON into the AGENT_WEBHOOK_TOOLS environment variable.
	Tools []WebhookToolSpec `json:"tools,omitempty"`

	// NotifyRef references an ArkNotify policy in the same namespace.
	// Used only for AgentDegraded events.
	// +optional
	NotifyRef *LocalObjectReference `json:"notifyRef,omitempty"`

	// BudgetRef references an ArkBudget in the same namespace that governs token
	// spend for this agent. When the budget is exhausted, new tasks are rejected.
	// +optional
	BudgetRef *LocalObjectReference `json:"budgetRef,omitempty"`

	// RegistryRef names the ArkRegistry in the same namespace that this agent
	// registers into. Defaults to "default". Set to "" (explicit empty string) to
	// opt out of all registry indexing.
	// +kubebuilder:default=default
	// +optional
	RegistryRef string `json:"registryRef,omitempty"`

	// Autoscaling configures KEDA-based autoscaling for this agent's deployment.
	// When enabled, a KEDA ScaledObject is created that scales replicas based on
	// Redis task queue depth. Requires KEDA v2 installed in the cluster.
	// +optional
	Autoscaling *ArkAgentAutoscaling `json:"autoscaling,omitempty"`

	// APIKeyRef references an ArkSecret in the same namespace that provides the LLM
	// provider API key for this agent. When set, the operator injects the key as an
	// explicit environment variable, overriding the arkonis-api-keys Secret fallback.
	// Updating the ArkSecret (or its referenced k8s Secret) triggers a rolling restart.
	// +optional
	APIKeyRef *LocalObjectReference `json:"apiKeyRef,omitempty"`

	// Capabilities advertises what this agent can do to ArkRegistry.
	// Agents without capabilities are invisible to registry lookups.
	// +optional
	Capabilities []AgentCapability `json:"capabilities,omitempty"`

	// NetworkPolicy configures the NetworkPolicy generated for agent pods (RFC-0016).
	// When not set the operator uses "default" mode: DNS + Redis + open HTTPS egress.
	// +optional
	NetworkPolicy *ArkAgentNetworkPolicy `json:"networkPolicy,omitempty"`

	// EnvFrom injects environment variables from Secrets or ConfigMaps into agent pods.
	// Use this to supply API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENAI_BASE_URL,
	// etc.) on a per-agent basis. Entries listed here take precedence over the
	// global arkonis-api-keys Secret set via the Helm chart.
	// +optional
	EnvFrom []corev1.EnvFromSource `json:"envFrom,omitempty"`

	// Resources sets CPU and memory requests/limits for agent pods.
	// When not set the operator injects safe defaults:
	//   requests: cpu=100m, memory=128Mi
	//   limits:   cpu=500m, memory=512Mi, ephemeral-storage=256Mi
	// Set this field explicitly to override the defaults.
	// +optional
	Resources *corev1.ResourceRequirements `json:"resources,omitempty"`
}

type ArkAgentStatus struct {
	// ReadyReplicas is the number of agent pods ready to accept tasks.
	ReadyReplicas int32 `json:"readyReplicas,omitempty"`
	// Replicas is the total number of agent pods (ready or not).
	Replicas int32 `json:"replicas,omitempty"`
	// DesiredReplicas is the autoscaling-computed target replica count set by the owning
	// ArkTeam controller. Nil for standalone agents not managed by a team autoscaler.
	// Use this column to see what the autoscaler wants vs what spec.replicas declares.
	// +optional
	DesiredReplicas *int32 `json:"desiredReplicas,omitempty"`
	// ObservedGeneration is the .metadata.generation this status reflects.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
	// DailyTokenUsage is the sum of tokens consumed by this deployment in the rolling 24-hour
	// window. Populated only when spec.limits.maxDailyTokens is set.
	DailyTokenUsage *TokenUsage `json:"dailyTokenUsage,omitempty"`
	// MCPServers reports the last observed connectivity state of each configured
	// MCP server. Updated on every reconcile; stale when no MCP servers are configured.
	// +optional
	MCPServers []ArkAgentMCPStatus `json:"mcpServers,omitempty"`

	// SystemPromptHash is the SHA-256 hex digest of the resolved system prompt last
	// applied by the operator. The admission webhook uses this to detect unauthorised
	// prompt changes — updates that alter spec.systemPrompt are rejected unless the
	// caller holds the ark-prompt-admin ClusterRole (RFC-0016 Phase 4).
	// +optional
	SystemPromptHash string `json:"systemPromptHash,omitempty"`

	// ExposedMCPCapabilities lists the capability IDs currently advertised at the
	// MCP gateway for this agent. Empty when no capabilities have exposeMCP: true
	// or when the MCP gateway is not enabled.
	// +optional
	ExposedMCPCapabilities []string `json:"exposedMCPCapabilities,omitempty"`

	// Conditions reflect the current state of the ArkAgent.
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type ArkBudget struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// +required
	Spec ArkBudgetSpec `json:"spec"`

	// +optional
	Status ArkBudgetStatus `json:"status,omitempty"`
}

type ArkBudgetList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []ArkBudget `json:"items"`
}

type ArkBudgetSelector struct {
	// Namespace scopes this budget to a single namespace.
	// Empty means all namespaces in the cluster.
	// +optional
	Namespace string `json:"namespace,omitempty"`

	// Team scopes this budget to a single ArkTeam by name.
	// Empty means all teams in the selected namespace(s).
	// +optional
	Team string `json:"team,omitempty"`

	// MatchLabels selects ArkTeams by label. Applied in addition to Namespace/Team.
	// +optional
	MatchLabels map[string]string `json:"matchLabels,omitempty"`
}

type ArkBudgetSpec struct {
	// Selector scopes this budget to matching resources.
	// +kubebuilder:validation:Required
	Selector ArkBudgetSelector `json:"selector"`

	// Period is the rolling window for spend accumulation.
	// +kubebuilder:validation:Enum=daily;weekly;monthly
	// +kubebuilder:default=monthly
	// +optional
	Period string `json:"period,omitempty"`

	// Limit is the maximum spend in the configured currency for one period.
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:XValidation:rule="self >= 0",message="limit must be non-negative"
	Limit float64 `json:"limit"`

	// Currency is the ISO 4217 currency code. Must match the operator's CostProvider.
	// +kubebuilder:default=USD
	// +optional
	Currency string `json:"currency,omitempty"`

	// WarnAt is the percentage of the limit at which a BudgetWarning notification fires (0–100).
	// Zero disables warnings. Default: 80.
	// +kubebuilder:default=80
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:Maximum=100
	// +optional
	WarnAt int `json:"warnAt,omitempty"`

	// HardStop blocks new ArkRuns when the limit is exceeded.
	// When false (default), runs continue but a BudgetExceeded notification fires.
	// When true, new ArkRuns fail immediately with BudgetExceeded before any tokens are spent.
	// +kubebuilder:default=false
	// +optional
	HardStop bool `json:"hardStop,omitempty"`

	// NotifyRef references an ArkNotify policy for budget alerts.
	// Fires BudgetWarning (at warnAt%) and BudgetExceeded (at 100%).
	// +optional
	NotifyRef *LocalObjectReference `json:"notifyRef,omitempty"`
}

type ArkBudgetStatus struct {
	// Phase summarises the current budget state.
	// +kubebuilder:validation:Enum=OK;Warning;Exceeded
	Phase BudgetStatus `json:"phase,omitempty"`

	// SpentUSD is the total spend in the current period window.
	// +kubebuilder:validation:XIntOrString
	SpentUSD float64 `json:"spentUSD,omitempty"`

	// PctUsed is SpentUSD / Limit as a percentage (0–100).
	PctUsed float64 `json:"pctUsed,omitempty"`

	// PeriodStart is the start of the current budget window.
	// +optional
	PeriodStart *metav1.Time `json:"periodStart,omitempty"`

	// LastUpdated is when the status was last recalculated.
	// +optional
	LastUpdated *metav1.Time `json:"lastUpdated,omitempty"`

	// ObservedGeneration is the .metadata.generation this status reflects.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions reflect the current state of the budget.
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

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

	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// +required
	Spec ArkEventSpec `json:"spec"`

	// +optional
	Status ArkEventStatus `json:"status,omitempty"`
}

type ArkEventList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []ArkEvent `json:"items"`
}

type ArkEventSource struct {
	// Type is the source type: cron | webhook | team-output.
	// +kubebuilder:validation:Required
	Type TriggerSourceType `json:"type"`

	// Cron is a standard 5-field cron expression (minute hour dom month dow).
	// Only used when type=cron.
	// Example: "0 9 * * 1-5" (9am on weekdays)
	Cron string `json:"cron,omitempty"`

	// TeamOutput triggers when the named ArkTeam pipeline reaches a phase.
	// Only used when type=team-output.
	TeamOutput *TeamOutputSource `json:"teamOutput,omitempty"`
}

type ArkEventSpec struct {
	// Source defines what fires this trigger.
	// +kubebuilder:validation:Required
	Source ArkEventSource `json:"source"`

	// Targets is the list of team pipelines to dispatch when the trigger fires.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinItems=1
	Targets []ArkEventTarget `json:"targets"`

	// ConcurrencyPolicy controls what happens when the trigger fires while a previous
	// run is still in progress. Defaults to Allow.
	// +kubebuilder:default=Allow
	ConcurrencyPolicy ConcurrencyPolicy `json:"concurrencyPolicy,omitempty"`

	// Suspended pauses the trigger without deleting it.
	// +kubebuilder:default=false
	Suspended bool `json:"suspended,omitempty"`
}

type ArkEventStatus struct {
	// LastFiredAt is when the trigger last dispatched team runs.
	LastFiredAt *metav1.Time `json:"lastFiredAt,omitempty"`
	// NextFireAt is the next scheduled fire time (cron type only).
	NextFireAt *metav1.Time `json:"nextFireAt,omitempty"`
	// FiredCount is the total number of times this trigger has fired.
	FiredCount int64 `json:"firedCount,omitempty"`
	// WebhookURL is the URL to POST to in order to fire this trigger (webhook type only).
	// Requires --trigger-webhook-url to be configured on the operator.
	WebhookURL string `json:"webhookURL,omitempty"`
	// ObservedGeneration is the .metadata.generation this status reflects.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
	// Conditions reflect the current state of the trigger.
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type ArkEventTarget struct {
	// Team is the name of the ArkTeam to dispatch a pipeline run for.
	// Exactly one of Team or Agent must be set.
	// +optional
	Team string `json:"team,omitempty"`

	// Agent is the name of the ArkAgent to invoke directly.
	// When set, the event creates an ArkRun with spec.agent and spec.prompt.
	// Exactly one of Team or Agent must be set.
	// +optional
	Agent string `json:"agent,omitempty"`

	// Prompt is the task text submitted to the agent when Agent is set.
	// Supports Go template syntax evaluated with the trigger fire context:
	//   {{ .trigger.name }}    — trigger name
	//   {{ .trigger.firedAt }} — RFC3339 fire timestamp
	//   {{ .trigger.body.* }} — JSON fields from the webhook request body (webhook type only)
	//   {{ .trigger.output }} — upstream team output (team-output type only)
	// +optional
	Prompt string `json:"prompt,omitempty"`

	// Input values to set on the dispatched team pipeline, overriding the template team's inputs.
	// Values are Go template strings evaluated with the trigger fire context (same as Prompt).
	// Only used when Team is set.
	// +optional
	Input map[string]string `json:"input,omitempty"`
}

type ArkFlowStepPhase string

type ArkFlowStepStatus struct {
	// Name matches the step name in spec.
	Name string `json:"name"`
	// Phase is the current execution phase.
	Phase ArkFlowStepPhase `json:"phase"`
	// TaskID is the Redis stream message ID of the submitted task, used to
	// correlate results from the agent-tasks-results stream.
	TaskID string `json:"taskID,omitempty"`
	// Output is the agent's raw text response once the step has succeeded.
	Output string `json:"output,omitempty"`

	// OutputJSON is the agent's response as a JSON string, populated when the step
	// has an OutputSchema and the response is valid JSON. Downstream steps can
	// reference fields via "{{ .steps.<name>.data.<field> }}".
	OutputJSON string `json:"outputJSON,omitempty"`
	// StartTime is when the step started executing.
	StartTime *metav1.Time `json:"startTime,omitempty"`
	// CompletionTime is when the step finished (success or failure).
	CompletionTime *metav1.Time `json:"completionTime,omitempty"`
	// Message holds a human-readable status detail.
	Message string `json:"message,omitempty"`
	// Iterations is the number of times this step has been executed (for loop steps).
	Iterations int `json:"iterations,omitempty"`
	// TokenUsage reports the tokens consumed by this step's LLM calls.
	TokenUsage *TokenUsage `json:"tokenUsage,omitempty"`
	// CostUSD is the estimated dollar cost of this step's LLM calls, calculated
	// using the operator's configured CostProvider. Zero for unknown/local models.
	CostUSD float64 `json:"costUSD,omitempty"`
	// ValidationAttempts counts how many times output validation has been run on this step.
	// Incremented on each validation attempt; reset when the step is retried from Pending.
	ValidationAttempts int `json:"validationAttempts,omitempty"`
	// ValidationMessage holds the most recent validation failure reason.
	// Cleared when validation passes.
	ValidationMessage string `json:"validationMessage,omitempty"`
	// Artifacts maps artifact names to their storage URLs or local paths.
	// Populated after the step completes when spec.artifactStore is configured.
	// Downstream steps reference artifacts via "{{ .steps.<name>.artifacts.<key> }}".
	Artifacts map[string]string `json:"artifacts,omitempty"`

	// ResolvedAgent is the ArkAgent name selected by a registry lookup for this step.
	// Empty when the step uses a static role reference.
	// +optional
	ResolvedAgent string `json:"resolvedAgent,omitempty"`

	// SelectedCapability is the capability ID chosen by the router LLM.
	// Only set for the synthetic "route" step in routed-mode runs.
	// +optional
	SelectedCapability string `json:"selectedCapability,omitempty"`

	// RoutingReason is the router LLM's one-sentence explanation for its choice.
	// Only set for the synthetic "route" step in routed-mode runs.
	// +optional
	RoutingReason string `json:"routingReason,omitempty"`
}

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

	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// +required
	Spec ArkMemorySpec `json:"spec"`

	// +optional
	Status ArkMemoryStatus `json:"status,omitempty"`
}

type ArkMemoryList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []ArkMemory `json:"items"`
}

type ArkMemorySpec struct {
	// Backend selects the memory storage strategy.
	// +kubebuilder:validation:Required
	Backend MemoryBackend `json:"backend"`

	// Redis configures the Redis backend. Required when backend is "redis".
	Redis *RedisMemoryConfig `json:"redis,omitempty"`

	// VectorStore configures the vector-store backend. Required when backend is "vector-store".
	VectorStore *VectorStoreMemoryConfig `json:"vectorStore,omitempty"`
}

type ArkMemoryStatus struct {
	// ObservedGeneration is the .metadata.generation this status reflects.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions reflect the current state of the ArkMemory.
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

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

	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// +required
	Spec ArkNotifySpec `json:"spec"`

	// +optional
	Status ArkNotifyStatus `json:"status,omitempty"`
}

type ArkNotifyList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []ArkNotify `json:"items"`
}

type ArkNotifySpec struct {
	// On lists the events that trigger notifications.
	// If empty, all events fire.
	// +optional
	On []NotifyEvent `json:"on,omitempty"`

	// Channels lists the notification targets.
	// +kubebuilder:validation:MinItems=1
	Channels []NotifyChannelSpec `json:"channels"`

	// RateLimitSeconds is the minimum interval between notifications for the
	// same (team, event) pair. Default: 300. Set to 0 to disable rate limiting.
	// +kubebuilder:default=300
	// +kubebuilder:validation:Minimum=0
	// +optional
	RateLimitSeconds int `json:"rateLimitSeconds,omitempty"`
}

type ArkNotifyStatus struct {
	// LastDispatches records the most recent dispatch result per channel index.
	// +optional
	LastDispatches []NotifyDispatchResult `json:"lastDispatches,omitempty"`
	// Conditions reflect the current state of the ArkNotify.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

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

	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// +optional
	Spec ArkRegistrySpec `json:"spec,omitempty"`

	// +optional
	Status ArkRegistryStatus `json:"status,omitempty"`
}

type ArkRegistryList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []ArkRegistry `json:"items"`
}

type ArkRegistryPolicy struct {
	// MaxDepth is the maximum agent-to-agent delegation depth.
	// Prevents runaway recursion.
	// +kubebuilder:default=3
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=20
	MaxDepth int `json:"maxDepth,omitempty"`

	// AllowCrossTeam permits resolution of agents managed by other ArkTeams.
	// Default false — only agents not owned by another team's inline roles.
	// +kubebuilder:default=false
	AllowCrossTeam bool `json:"allowCrossTeam,omitempty"`
}

type ArkRegistrySpec struct {
	// Scope controls which ArkAgents are indexed.
	// namespace-scoped: only ArkAgents in the same namespace (default).
	// cluster-wide: all ArkAgents cluster-wide (requires ClusterRole).
	// +kubebuilder:default=namespace-scoped
	// +kubebuilder:validation:Enum=namespace-scoped;cluster-wide
	Scope RegistryScope `json:"scope,omitempty"`

	// Policy controls delegation safety.
	// +optional
	Policy *ArkRegistryPolicy `json:"policy,omitempty"`

	// MCPBindings maps capability IDs to MCP server URLs for this deployment.
	// Agents that declare mcpServers with capabilityRef have their URLs resolved
	// from this list at reconcile time. This allows cookbook-style agent definitions
	// to remain URL-free; operators supply the bindings per namespace.
	// +optional
	MCPBindings []MCPBinding `json:"mcpBindings,omitempty"`
}

type ArkRegistryStatus struct {
	// IndexedAgents is the total number of ArkAgents indexed by this registry.
	IndexedAgents int `json:"indexedAgents,omitempty"`

	// Fleet is the list of ArkAgents currently registered with this registry,
	// with per-agent readiness and token usage. Replaces the implicit
	// "all agents in namespace" model with an explicit opt-in list.
	// +optional
	Fleet []AgentFleetEntry `json:"fleet,omitempty"`

	// LastRebuild is the time the index was last rebuilt.
	// +optional
	LastRebuild *metav1.Time `json:"lastRebuild,omitempty"`

	// Capabilities lists all capabilities indexed, with their associated agents and tags.
	// +optional
	Capabilities []IndexedCapability `json:"capabilities,omitempty"`

	// ObservedGeneration is the .metadata.generation this status reflects.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions reflect the current state of the ArkRegistry.
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type ArkRun struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// +required
	Spec ArkRunSpec `json:"spec"`

	// +optional
	Status ArkRunStatus `json:"status,omitempty"`
}

type ArkRunList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []ArkRun `json:"items"`
}

type ArkRunPhase string

type ArkRunSpec struct {
	// TeamRef is the name of the ArkTeam that owns this run.
	// Exactly one of TeamRef or Agent must be set.
	// +optional
	TeamRef string `json:"teamRef,omitempty"`

	// Agent is the name of the ArkAgent to invoke for a standalone run.
	// Exactly one of TeamRef or Agent must be set.
	// +optional
	Agent string `json:"agent,omitempty"`

	// Prompt is the task text submitted to the agent for a standalone run.
	// Required when Agent is set.
	// +optional
	Prompt string `json:"prompt,omitempty"`

	// TeamGeneration is the ArkTeam spec.generation at the time this run was
	// created. Allows correlating a run with the exact team spec that was in effect.
	// Only set for team runs.
	// +optional
	TeamGeneration int64 `json:"teamGeneration,omitempty"`

	// Input is the resolved input map for this run: team default inputs merged with
	// any per-trigger overrides supplied via ark trigger --input or ArkEvent.
	// Step inputs reference these values via "{{ .input.<key> }}".
	// +optional
	Input map[string]string `json:"input,omitempty"`

	// Pipeline is a snapshot of the ArkTeam pipeline DAG at trigger time.
	// Empty for routed-mode runs.
	// +optional
	Pipeline []ArkTeamPipelineStep `json:"pipeline,omitempty"`

	// Roles is a snapshot of the ArkTeam role definitions at trigger time.
	// Empty for routed-mode runs.
	// +optional
	Roles []ArkTeamRole `json:"roles,omitempty"`

	// Output is a Go template expression that selects the final run result.
	// Example: "{{ .steps.summarize.output }}"
	// For routed-mode runs this defaults to "{{ .steps.route.output }}" at trigger time.
	// +optional
	Output string `json:"output,omitempty"`

	// Routing is a snapshot of the ArkTeam routing config at trigger time.
	// Set when the team operates in routed mode. Mutually exclusive with Pipeline.
	// +optional
	Routing *ArkTeamRoutingSpec `json:"routing,omitempty"`

	// TimeoutSeconds is the maximum wall-clock seconds this run may take.
	// Zero means no timeout.
	// +kubebuilder:validation:Minimum=1
	// +optional
	TimeoutSeconds int `json:"timeoutSeconds,omitempty"`

	// MaxTokens is the total token budget for this run across all steps.
	// Zero means no limit.
	// +kubebuilder:validation:Minimum=1
	// +optional
	MaxTokens int64 `json:"maxTokens,omitempty"`
}

type ArkRunStatus struct {
	// Phase is the overall execution state.
	Phase ArkRunPhase `json:"phase,omitempty"`

	// Steps holds the per-step execution state for this run, including full
	// step outputs. Unlike ArkTeam.Status, this is never reset — it is the
	// permanent record of what happened during this run.
	Steps []ArkFlowStepStatus `json:"steps,omitempty"`

	// Output is the resolved final pipeline output once phase is Succeeded.
	Output string `json:"output,omitempty"`

	// StartTime is when this run began executing.
	StartTime *metav1.Time `json:"startTime,omitempty"`

	// CompletionTime is when this run reached a terminal phase (Succeeded or Failed).
	CompletionTime *metav1.Time `json:"completionTime,omitempty"`

	// TotalTokenUsage is the sum of token usage across all steps in this run.
	TotalTokenUsage *TokenUsage `json:"totalTokenUsage,omitempty"`

	// TotalCostUSD is the estimated total dollar cost of this run, summed across
	// all steps using the operator's configured CostProvider.
	TotalCostUSD float64 `json:"totalCostUSD,omitempty"`

	// ObservedGeneration is the .metadata.generation this status reflects.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions reflect the current state of the ArkRun.
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

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

	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// +required
	Spec ArkSecretSpec `json:"spec"`

	// +optional
	Status ArkSecretStatus `json:"status,omitempty"`
}

type ArkSecretList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []ArkSecret `json:"items"`
}

type ArkSecretPhase string

type ArkSecretProvider string

type ArkSecretSpec struct {
	// Provider identifies the LLM provider this key is for.
	// Determines which environment variable is injected into agent pods:
	//   anthropic → ANTHROPIC_API_KEY
	//   openai    → OPENAI_API_KEY
	//   generic   → value of spec.envVar
	// +kubebuilder:validation:Required
	Provider ArkSecretProvider `json:"provider"`

	// SecretKeyRef references the Kubernetes Secret key that holds the API key value.
	// The referenced Secret must exist in the same namespace as the ArkSecret.
	// +kubebuilder:validation:Required
	SecretKeyRef corev1.SecretKeySelector `json:"secretKeyRef"`

	// EnvVar is the environment variable name to inject when provider is "generic".
	// Ignored for anthropic and openai providers.
	// +optional
	EnvVar string `json:"envVar,omitempty"`
}

type ArkSecretStatus struct {
	// Phase is Active when the referenced Secret key exists and is non-empty, Invalid otherwise.
	// +optional
	Phase ArkSecretPhase `json:"phase,omitempty"`

	// ObservedGeneration is the .metadata.generation this status reflects.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions reflect the current state of the ArkSecret.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

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

	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// +required
	Spec ArkSettingsSpec `json:"spec"`

	// +optional
	Status ArkSettingsStatus `json:"status,omitempty"`
}

type ArkSettingsList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []ArkSettings `json:"items"`
}

type ArkSettingsSecurity struct {
	// MCPAllowlist is a list of URL prefixes. When set, the admission webhook rejects
	// ArkAgent specs that reference MCP server URLs not matching any listed prefix.
	// Use this to prevent agents from calling arbitrary external MCP endpoints (T9).
	// Example: ["https://search.mcp.example.com/", "https://browser.mcp.example.com/"]
	// +optional
	MCPAllowlist []string `json:"mcpAllowlist,omitempty"`

	// RequireMCPAuth: when true, the webhook rejects ArkAgent specs that declare MCP
	// servers without an auth configuration (spec.mcpServers[*].auth.type must not be "none").
	// Ensures no agent can call an MCP server without verified credentials.
	// +optional
	RequireMCPAuth bool `json:"requireMCPAuth,omitempty"`
}

type ArkSettingsSpec struct {
	// Temperature controls response randomness (0.0–1.0).
	// +kubebuilder:validation:Pattern=`^(0(\.[0-9]+)?|1(\.0+)?)$`
	Temperature string `json:"temperature,omitempty"`

	// OutputFormat specifies the expected output format (e.g. "structured-json").
	OutputFormat string `json:"outputFormat,omitempty"`

	// MemoryBackend defines where agent memory is stored.
	// +kubebuilder:default=in-context
	MemoryBackend MemoryBackend `json:"memoryBackend,omitempty"`

	// Fragments is an ordered list of named prompt fragments composed into the agent system prompt.
	// Fragments from all referenced ArkSettings are applied in settingsRefs list order.
	// When the same fragment name appears in multiple settings, the last occurrence wins.
	// +optional
	Fragments []PromptFragment `json:"fragments,omitempty"`

	// PromptFragments is deprecated. Use Fragments instead.
	// When both are set, Fragments takes precedence and PromptFragments is ignored.
	// Retained for backward compatibility; will be removed in v1beta1.
	// +optional
	PromptFragments *PromptFragments `json:"promptFragments,omitempty"`

	// Security configures MCP server access policy enforced by the admission webhook.
	// The strictest policy across all referenced ArkSettings wins.
	// +optional
	Security *ArkSettingsSecurity `json:"security,omitempty"`
}

type ArkSettingsStatus struct {
	// ObservedGeneration is the .metadata.generation this status reflects.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
	// Conditions reflect the current state of the ArkSettings.
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type ArkTeam struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// +required
	Spec ArkTeamSpec `json:"spec"`

	// +optional
	Status ArkTeamStatus `json:"status,omitempty"`
}

type ArkTeamAutoscaling struct {
	// Enabled turns on team-owned autoscaling. When false the operator does not touch replicas.
	// +optional
	Enabled bool `json:"enabled,omitempty"`

	// ScaleToZero configures idle scale-to-zero.
	// When unset, roles are always kept at their configured replica count.
	// +optional
	ScaleToZero *ArkTeamScaleToZero `json:"scaleToZero,omitempty"`
}

type ArkTeamInputSpec struct {
	// Name is the parameter key, referenced in step prompts via "{{ .input.<name> }}".
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Name string `json:"name"`

	// Type is the expected type of the value, used for documentation and tooling.
	// The operator enforces presence/default but does not coerce string values.
	// +kubebuilder:validation:Enum=string;number;boolean;object;array
	// +kubebuilder:default=string
	// +optional
	Type string `json:"type,omitempty"`

	// Description documents the parameter for operators and tooling.
	// +optional
	Description string `json:"description,omitempty"`

	// Required marks this parameter as mandatory. When true and the parameter is
	// absent from spec.input at run creation, the ArkRun is immediately failed.
	// +optional
	Required bool `json:"required,omitempty"`

	// Default is the value applied when Required is false and the parameter
	// is not provided in spec.input.
	// +optional
	Default string `json:"default,omitempty"`
}

type ArkTeamLimits struct {
	// MaxDailyTokens is the rolling 24-hour token budget across the whole team pipeline.
	// Zero means no daily limit.
	// +kubebuilder:validation:Minimum=1
	MaxDailyTokens int64 `json:"maxDailyTokens,omitempty"`
}

type ArkTeamList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []ArkTeam `json:"items"`
}

type ArkTeamPhase string

type ArkTeamPipelineStep struct {
	// Role references a role name in spec.roles. The step name equals the role name.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Role string `json:"role"`

	// Inputs is a map of input key → Go template expression referencing pipeline
	// inputs or earlier step outputs. Example: "{{ .steps.research.output }}"
	Inputs map[string]string `json:"inputs,omitempty"`

	// DependsOn lists role names (step names) that must complete before this step runs.
	DependsOn []string `json:"dependsOn,omitempty"`

	// If is an optional Go template expression. When set, the step only executes if the
	// expression evaluates to a truthy value. A falsy result marks the step Skipped.
	If string `json:"if,omitempty"`

	// Loop makes this step repeat until Condition evaluates to false or MaxIterations is reached.
	Loop *LoopSpec `json:"loop,omitempty"`

	// OutputSchema is an optional JSON Schema string that constrains this step's output.
	OutputSchema string `json:"outputSchema,omitempty"`

	// Validate configures optional output validation for this step.
	// When set, the step enters Validating phase after the agent completes and only
	// transitions to Succeeded once all configured checks pass.
	// +optional
	Validate *StepValidation `json:"validate,omitempty"`

	// OutputArtifacts declares file artifacts this step produces.
	// The agent writes each artifact to $AGENT_ARTIFACT_DIR/<name> after its task.
	// Artifact URLs are stored in ArkFlowStepStatus.Artifacts and available to
	// downstream steps via "{{ .steps.<stepName>.artifacts.<name> }}".
	// +optional
	OutputArtifacts []ArtifactSpec `json:"outputArtifacts,omitempty"`

	// InputArtifacts maps a local artifact name to an upstream step's artifact.
	// The value format is "<stepName>.<artifactName>".
	// The resolved URL is injected via AGENT_INPUT_ARTIFACTS env var as a JSON map.
	// +optional
	InputArtifacts map[string]string `json:"inputArtifacts,omitempty"`

	// RegistryLookup resolves the executing agent by capability at runtime.
	// The ArkRun controller resolves this before the step starts and records
	// the resolved agent in status.resolvedAgent.
	// +optional
	RegistryLookup *RegistryLookupSpec `json:"registryLookup,omitempty"`
}

type ArkTeamRole struct {
	// Name is the unique role identifier (e.g. "researcher", "coordinator").
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Name string `json:"name"`

	// ArkAgent is the name of an existing ArkAgent in the same namespace.
	// Mutually exclusive with Model+SystemPrompt (inline definition).
	// +optional
	ArkAgent string `json:"arkAgent,omitempty"`

	// ArkTeam is the name of another ArkTeam in the same namespace whose entry role
	// fulfils this role. Only valid in pipeline mode (spec.pipeline must be set).
	// +optional
	ArkTeam string `json:"arkTeam,omitempty"`

	// Model is the LLM model ID for an inline role definition.
	// If set, the operator auto-creates an ArkAgent named {team}-{role}.
	// +optional
	Model string `json:"model,omitempty"`

	// SystemPrompt is the inline system prompt for an auto-created ArkAgent.
	//
	// Deprecated for production use: inline prompts are stored directly in etcd
	// and can exceed the 1.5 MB per-object limit when prompts are large or when
	// many roles are defined in one ArkTeam. Use SystemPromptRef instead for any
	// prompt larger than ~50 KB or for any production workload.
	//
	// Inline prompts remain fully supported for local development, quickstart
	// examples, and prompts under 50 KB.
	// +optional
	SystemPrompt string `json:"systemPrompt,omitempty"`

	// SystemPromptRef references a ConfigMap or Secret key whose content is used
	// as the system prompt for this role's auto-created ArkAgent. Takes precedence
	// over SystemPrompt when both are set. Preferred for production workloads —
	// prompt text is stored in a ConfigMap/Secret rather than in etcd as part of
	// the ArkTeam object, avoiding etcd size limits.
	// +optional
	SystemPromptRef *SystemPromptSource `json:"systemPromptRef,omitempty"`

	// MCPServers lists MCP tool servers for an inline role definition.
	// +optional
	MCPServers []MCPServerSpec `json:"mcpServers,omitempty"`

	// Tools lists inline HTTP webhook tools for an inline role definition.
	// +optional
	Tools []WebhookToolSpec `json:"tools,omitempty"`

	// Replicas is the number of agent pods for an inline role definition.
	// +kubebuilder:default=1
	// +optional
	Replicas *int32 `json:"replicas,omitempty"`

	// Limits constrains per-agent resource usage for an inline role definition.
	// +optional
	Limits *ArkonisLimits `json:"limits,omitempty"`

	// Resources sets CPU and memory requests/limits for the agent pods of an inline role
	// definition. When not set the operator injects safe defaults (requests: cpu=100m
	// mem=128Mi; limits: cpu=500m mem=512Mi ephemeral-storage=256Mi). Set this field
	// explicitly to tune for your workload's actual footprint.
	// +optional
	Resources *corev1.ResourceRequirements `json:"resources,omitempty"`

	// Autoscaling configures KEDA-based autoscaling for an inline role's managed ArkAgent.
	// +optional
	Autoscaling *ArkAgentAutoscaling `json:"autoscaling,omitempty"`

	// CanDelegate lists role names this role is permitted to call via delegate().
	// Empty means this is a leaf role — it cannot delegate further.
	// +optional
	CanDelegate []string `json:"canDelegate,omitempty"`

	// SettingsRefs references one or more ArkSettings whose fragments are composed into this
	// role's system prompt, in list order. Only applies to inline roles (those with model +
	// systemPrompt/systemPromptRef). For roles referencing an external ArkAgent (arkAgent: <name>),
	// set settingsRefs on the ArkAgent CR directly.
	// +optional
	SettingsRefs []LocalObjectReference `json:"settingsRefs,omitempty"`

	// EnvFrom injects environment variables from Secrets or ConfigMaps into the agent pods
	// created for this role. Use this to supply API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY,
	// OPENAI_BASE_URL, etc.) on a per-role basis. Entries listed here take precedence over
	// the global arkonis-api-keys Secret set via the Helm chart.
	// Only applies to inline roles (those with model + systemPrompt/systemPromptRef).
	// +optional
	EnvFrom []corev1.EnvFromSource `json:"envFrom,omitempty"`
}

type ArkTeamRoleStatus struct {
	// Name matches ArkTeamRole.Name.
	Name string `json:"name"`
	// ReadyReplicas is the number of agent pods ready to accept tasks.
	ReadyReplicas int32 `json:"readyReplicas,omitempty"`
	// DesiredReplicas is the configured replica count for this role.
	DesiredReplicas int32 `json:"desiredReplicas,omitempty"`
	// ManagedArkAgent is the name of the auto-created ArkAgent for inline roles.
	ManagedArkAgent string `json:"managedArkAgent,omitempty"`
}

type ArkTeamRoutingSpec struct {
	// RegistryRef names the ArkRegistry to query for capability resolution.
	// Defaults to the first ArkRegistry found in the namespace when omitted.
	// +optional
	RegistryRef *LocalObjectReference `json:"registryRef,omitempty"`

	// Model is the LLM model used for the router call.
	// A lightweight model (e.g. haiku) is sufficient and recommended.
	// Defaults to the operator-wide default model when omitted.
	// +kubebuilder:validation:MinLength=1
	// +optional
	Model string `json:"model,omitempty"`

	// SystemPrompt overrides the default router system prompt.
	// Use {{ .Capabilities }} to embed the capability list and
	// {{ .Input }} to embed the task input in a custom prompt.
	// +optional
	SystemPrompt string `json:"systemPrompt,omitempty"`

	// Fallback is the name of a standalone ArkAgent to use when no capability
	// matches or the router LLM fails to select one.
	// When absent and no match is found, the run fails with RoutingFailed.
	// +optional
	Fallback string `json:"fallback,omitempty"`

	// MaxHops is the maximum number of sequential routing decisions per run.
	// Reserved for future multi-hop support. Must be 1 in this version.
	// +kubebuilder:default=1
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=1
	// +optional
	MaxHops int `json:"maxHops,omitempty"`
}

type ArkTeamScaleToZero struct {
	// Enabled activates scale-to-zero. When true, idle roles are scaled to 0 replicas after
	// AfterSeconds of inactivity and are warmed back up automatically when a new run triggers.
	// +optional
	Enabled bool `json:"enabled,omitempty"`

	// AfterSeconds is how long a role must be idle (no active steps) before it is scaled to zero.
	// Minimum 30. Defaults to 300 (5 minutes).
	// +kubebuilder:default=300
	// +kubebuilder:validation:Minimum=30
	// +optional
	AfterSeconds *int32 `json:"afterSeconds,omitempty"`
}

type ArkTeamSpec struct {
	// Entry is the role name that receives external tasks in dynamic mode.
	// Exactly one role should be the entry point for dynamic teams.
	// In pipeline mode (spec.pipeline set), entry is optional.
	// +optional
	Entry string `json:"entry,omitempty"`

	// Output is a Go template expression that selects the final pipeline result.
	// Example: "{{ .steps.summarize.output }}"
	// Only used in pipeline mode.
	// +optional
	Output string `json:"output,omitempty"`

	// Inputs defines the formal schema for pipeline input parameters.
	// When set, required parameters are enforced and defaults are applied before
	// an ArkRun starts executing. Steps reference these values via "{{ .input.<name> }}".
	// +optional
	Inputs []ArkTeamInputSpec `json:"inputs,omitempty"`

	// Input is the initial data passed into the pipeline.
	// Step inputs can reference these values via "{{ .input.<key> }}".
	// Only used in pipeline mode.
	// +optional
	Input map[string]string `json:"input,omitempty"`

	// TimeoutSeconds is the maximum wall-clock seconds the pipeline may run.
	// Zero means no timeout. Only used in pipeline mode.
	// +kubebuilder:validation:Minimum=1
	// +optional
	TimeoutSeconds int `json:"timeoutSeconds,omitempty"`

	// MaxTokens is the total token budget for the entire pipeline run.
	// Zero means no limit. Only used in pipeline mode.
	// +kubebuilder:validation:Minimum=1
	// +optional
	MaxTokens int64 `json:"maxTokens,omitempty"`

	// Limits constrains team-level resource usage.
	// +optional
	Limits *ArkTeamLimits `json:"limits,omitempty"`

	// Roles defines the roles that make up this team.
	// At least one role is required unless spec.routing is set (routed mode).
	// +optional
	Roles []ArkTeamRole `json:"roles,omitempty"`

	// Pipeline defines an optional DAG of steps that drive ordered execution.
	// When set, the team operates in pipeline mode (job semantics).
	// When unset, the team operates in dynamic mode (service semantics).
	// +optional
	Pipeline []ArkTeamPipelineStep `json:"pipeline,omitempty"`

	// SuccessfulRunsHistoryLimit is the number of successful ArkRun objects to
	// retain for this team. Oldest runs beyond this limit are deleted automatically.
	// Set to 0 to delete successful runs immediately after completion.
	// +kubebuilder:default=10
	// +kubebuilder:validation:Minimum=0
	// +optional
	SuccessfulRunsHistoryLimit *int32 `json:"successfulRunsHistoryLimit,omitempty"`

	// FailedRunsHistoryLimit is the number of failed ArkRun objects to retain.
	// +kubebuilder:default=3
	// +kubebuilder:validation:Minimum=0
	// +optional
	FailedRunsHistoryLimit *int32 `json:"failedRunsHistoryLimit,omitempty"`

	// RunRetainFor is the maximum age of completed ArkRun objects for this team.
	// Runs older than this duration are deleted regardless of the history limits.
	// Zero means no age-based cleanup (only count-based limits apply).
	// Example: "168h" (7 days), "720h" (30 days).
	// +optional
	RunRetainFor *metav1.Duration `json:"runRetainFor,omitempty"`

	// NotifyRef references an ArkNotify policy in the same namespace.
	// When set, the operator dispatches notifications after terminal phase transitions.
	// +optional
	NotifyRef *LocalObjectReference `json:"notifyRef,omitempty"`

	// BudgetRef references an ArkBudget in the same namespace that governs token
	// spend for this team. When the budget is exhausted, new runs are blocked.
	// +optional
	BudgetRef *LocalObjectReference `json:"budgetRef,omitempty"`

	// RegistryRef names the ArkRegistry used for registryLookup steps and routed
	// mode agent resolution. Defaults to "default".
	// +kubebuilder:default=default
	// +optional
	RegistryRef string `json:"registryRef,omitempty"`

	// ArtifactStore configures where pipeline file artifacts are stored.
	// When unset, file artifact support is disabled and any OutputArtifacts
	// declarations on pipeline steps are ignored.
	// +optional
	ArtifactStore *ArtifactStoreSpec `json:"artifactStore,omitempty"`

	// Autoscaling configures demand-driven replica scaling for this team's inline agents.
	// When enabled, the operator scales each role's managed ArkAgent between 0 and its
	// configured replica count based on the number of active pipeline steps for that role.
	// Only applies to inline roles (those with model+systemPrompt); external ArkAgent references
	// are not scaled by the team controller.
	// +optional
	Autoscaling *ArkTeamAutoscaling `json:"autoscaling,omitempty"`

	// Routing configures routed mode. When set, the team operates in routed mode:
	// tasks are dispatched automatically via an LLM router call against ArkRegistry.
	// Mutually exclusive with spec.pipeline and spec.roles.
	// +optional
	Routing *ArkTeamRoutingSpec `json:"routing,omitempty"`
}

type ArkTeamStatus struct {
	// Phase is the overall team state.
	// For pipeline teams this mirrors the most recent ArkRun phase.
	// For dynamic teams this reflects infrastructure readiness.
	Phase ArkTeamPhase `json:"phase,omitempty"`

	// Roles lists the observed state of each role.
	Roles []ArkTeamRoleStatus `json:"roles,omitempty"`

	// EntryRole is the role name that is the external submission point.
	EntryRole string `json:"entryRole,omitempty"`

	// LastRunName is the name of the most recently created ArkRun for this team.
	// Empty when no run has been triggered yet.
	LastRunName string `json:"lastRunName,omitempty"`

	// LastRunPhase is the phase of the most recently created ArkRun.
	// Mirrors ArkRun.Status.Phase for quick visibility in kubectl get arkteam.
	LastRunPhase ArkRunPhase `json:"lastRunPhase,omitempty"`

	// ScaledToZero is true when all inline-role agents have been scaled to 0 replicas
	// due to team autoscaling idle timeout. The team warms up automatically when triggered.
	// +optional
	ScaledToZero bool `json:"scaledToZero,omitempty"`

	// LastActiveTime is when the team last had an active (running) pipeline step.
	// Used by the autoscaler to decide when to scale idle roles to zero.
	// +optional
	LastActiveTime *metav1.Time `json:"lastActiveTime,omitempty"`

	// ObservedGeneration is the .metadata.generation this status reflects.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions reflect the current state of the ArkTeam.
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type ArkonisLimits struct {
	// MaxTokensPerCall is the maximum number of tokens per Anthropic API call.
	// +kubebuilder:default=8000
	MaxTokensPerCall int `json:"maxTokensPerCall,omitempty"`
	// MaxConcurrentTasks is the maximum number of tasks processed in parallel per replica.
	// +kubebuilder:default=5
	MaxConcurrentTasks int `json:"maxConcurrentTasks,omitempty"`
	// TimeoutSeconds is the per-task deadline.
	// +kubebuilder:default=120
	TimeoutSeconds int `json:"timeoutSeconds,omitempty"`
	// MaxDailyTokens is the rolling 24-hour token budget (input + output combined) for this
	// deployment. When the budget is reached, the operator scales replicas to 0 and sets a
	// BudgetExceeded condition. The deployment resumes automatically once the 24-hour window
	// rotates and usage drops below the limit. Zero means no daily limit.
	// +kubebuilder:validation:Minimum=1
	MaxDailyTokens int64 `json:"maxDailyTokens,omitempty"`
}

type ArkonisProbe struct {
	// Type is the probe strategy: "semantic" (LLM-based) or "ping" (HTTP).
	Type ProbeType `json:"type"`
	// IntervalSeconds is how often the probe runs.
	// +kubebuilder:default=30
	IntervalSeconds int `json:"intervalSeconds,omitempty"`
	// ValidatorPrompt is the prompt sent when Type is "semantic".
	ValidatorPrompt string `json:"validatorPrompt,omitempty"`
}

type ArtifactSpec struct {
	// Name is the artifact identifier, used in template references:
	// {{ .steps.<stepName>.artifacts.<name> }}
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Name string `json:"name"`
	// Description documents the artifact for operators and tooling.
	// +optional
	Description string `json:"description,omitempty"`
	// ContentType is the MIME type hint for the artifact (e.g. application/pdf).
	// +optional
	ContentType string `json:"contentType,omitempty"`
}

type ArtifactStoreGCSSpec struct {
	// Bucket is the GCS bucket name.
	// +kubebuilder:validation:Required
	Bucket string `json:"bucket"`
	// Prefix is an optional object prefix applied to all stored artifacts.
	// +optional
	Prefix string `json:"prefix,omitempty"`
	// CredentialsSecret references a k8s Secret with a service account JSON key
	// under the "credentials.json" key.
	// +optional
	CredentialsSecret *LocalObjectReference `json:"credentialsSecret,omitempty"`
}

type ArtifactStoreLocalSpec struct {
	// Path is the base directory where artifacts are stored.
	// Defaults to /tmp/ark-artifacts when empty.
	// +optional
	Path string `json:"path,omitempty"`
}

type ArtifactStoreS3Spec struct {
	// Bucket is the S3 bucket name.
	// +kubebuilder:validation:Required
	Bucket string `json:"bucket"`
	// Region is the AWS region (e.g. us-east-1).
	// +optional
	Region string `json:"region,omitempty"`
	// Prefix is an optional key prefix applied to all stored artifacts.
	// +optional
	Prefix string `json:"prefix,omitempty"`
	// CredentialsSecret references a k8s Secret containing AWS_ACCESS_KEY_ID
	// and AWS_SECRET_ACCESS_KEY keys. When empty, the default credential chain is used.
	// +optional
	CredentialsSecret *LocalObjectReference `json:"credentialsSecret,omitempty"`
}

type ArtifactStoreSpec struct {
	// Type selects the storage backend.
	// +kubebuilder:validation:Required
	Type ArtifactStoreType `json:"type"`
	// Local configures local-disk storage. Only used when type=local.
	// +optional
	Local *ArtifactStoreLocalSpec `json:"local,omitempty"`
	// S3 configures Amazon S3 storage. Only used when type=s3.
	// +optional
	S3 *ArtifactStoreS3Spec `json:"s3,omitempty"`
	// GCS configures Google Cloud Storage. Only used when type=gcs.
	// +optional
	GCS *ArtifactStoreGCSSpec `json:"gcs,omitempty"`
}

type ArtifactStoreType string

type BudgetStatus string

type ConcurrencyPolicy string

type IndexedCapability struct {
	// ID is the capability identifier.
	ID string `json:"id"`
	// Description is the human-readable description of the capability, taken from the
	// first agent that declares it. Used by the router LLM to select the right agent.
	Description string `json:"description,omitempty"`
	// Agents is the list of ArkAgent names that advertise this capability.
	Agents []string `json:"agents,omitempty"`
	// Tags is the union of all tags declared for this capability across all agents.
	Tags []string `json:"tags,omitempty"`
}

type LocalObjectReference struct {
	// Name of the referenced object.
	Name string `json:"name"`
}

type LoopSpec struct {
	// Condition is a Go template expression evaluated after each iteration.
	// The step repeats while this evaluates to a truthy value ("true", non-empty, non-"false", non-"0").
	// Example: "{{ gt (len .steps.collect.output) 0 }}"
	// +kubebuilder:validation:Required
	Condition string `json:"condition"`

	// MaxIterations caps the number of loop repetitions to prevent infinite loops.
	// +kubebuilder:default=10
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=100
	MaxIterations int `json:"maxIterations,omitempty"`
}

type MCPBinding struct {
	// CapabilityID is the capability identifier to resolve.
	// Must match MCPServerSpec.capabilityRef on the referencing agent.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	CapabilityID string `json:"capabilityId"`
	// URL is the SSE endpoint of the MCP server that provides this capability.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	URL string `json:"url"`
}

type MCPHeaderValue struct {
	// Value is the literal header value. Use this for non-sensitive headers.
	// +optional
	Value string `json:"value,omitempty"`
	// SecretKeyRef selects a key of a Secret in the same namespace.
	// Use this when the header value contains credentials.
	// +optional
	SecretKeyRef *corev1.SecretKeySelector `json:"secretKeyRef,omitempty"`
}

type MCPServerAuth struct {
	// Type selects the authentication mechanism.
	// +kubebuilder:default=none
	// +kubebuilder:validation:Enum=none;bearer;mtls
	Type string `json:"type"`

	// TokenSecretRef references a k8s Secret containing the bearer token.
	// Required when type=bearer. The Secret key value is injected as an env var;
	// it is never inlined into the pod spec.
	// +optional
	TokenSecretRef *corev1.SecretKeySelector `json:"tokenSecretRef,omitempty"`

	// MTLSSecretRef references a k8s Secret containing tls.crt and tls.key.
	// Required when type=mtls. The Secret is mounted as a read-only volume inside
	// the agent pod; the cert paths are injected via AGENT_MCP_SERVERS JSON.
	// +optional
	MTLSSecretRef *LocalObjectReference `json:"mtlsSecretRef,omitempty"`
}

type MCPServerSpec struct {
	// Name is a human-readable identifier for this MCP server.
	Name string `json:"name"`
	// URL is the direct SSE endpoint of the MCP server.
	// Mutually exclusive with capabilityRef and arkAgentRef.
	// +optional
	URL string `json:"url,omitempty"`
	// CapabilityRef names a capability ID defined in the namespace's ArkRegistry.
	// The operator resolves the actual MCP server URL from the registry's mcpBindings
	// at reconcile time. Use this in shareable agent definitions (e.g. ark-cookbook)
	// so that the URL is supplied per-deployment rather than hardcoded.
	// Mutually exclusive with url and arkAgentRef.
	// +optional
	CapabilityRef string `json:"capabilityRef,omitempty"`
	// ArkAgentRef names an ArkAgent in the same namespace whose MCP-exposed capabilities
	// should be made available as tools to this agent. The operator resolves this to the
	// MCP gateway URL for the target agent at reconcile time. The target agent must have
	// at least one capability with exposeMCP: true.
	// Mutually exclusive with url and capabilityRef.
	// +optional
	ArkAgentRef string `json:"arkAgentRef,omitempty"`
	// Headers is an optional map of HTTP headers to send with every request to this MCP server.
	// Values can be literal strings or references to Kubernetes Secret keys.
	// +optional
	Headers map[string]MCPHeaderValue `json:"headers,omitempty"`
	// Guidance is optional deployment-specific instructions for using this MCP server.
	// When set, the operator appends a structured section to the agent's composed system prompt.
	// Use this for operational context that varies per deployment — branch policies, project keys,
	// environment-specific constraints. General tool documentation belongs in the MCP tool's own
	// description field, which the agent runtime already surfaces to the LLM via list_tools.
	// +optional
	Guidance string `json:"guidance,omitempty"`

	// Auth configures authentication for this MCP server connection.
	// Supports bearer token (Authorization: Bearer) and mTLS client certificates.
	// When not set the connection is unauthenticated (type: none).
	// +optional
	Auth *MCPServerAuth `json:"auth,omitempty"`
}

type MemoryBackend string

type NetworkPolicyMode string

type NotifyChannelSpec struct {
	// Type determines the channel implementation.
	// +kubebuilder:validation:Enum=webhook;slack
	Type NotifyChannelType `json:"type"`
	// Webhook configures a generic HTTP POST channel. Required when type is "webhook".
	// +optional
	Webhook *WebhookChannelSpec `json:"webhook,omitempty"`
	// Slack configures a Slack incoming webhook channel. Required when type is "slack".
	// +optional
	Slack *SlackChannelSpec `json:"slack,omitempty"`
	// Template is an optional Go template for the message body.
	// Context is NotifyPayload. Overrides the channel's default format.
	// For "webhook": template output is the raw POST body.
	// For "slack": template output replaces the default Block Kit message text.
	// +optional
	Template string `json:"template,omitempty"`
}

type NotifyChannelType string

type NotifyDispatchResult struct {
	// ChannelIndex is the zero-based index of the channel in spec.channels.
	ChannelIndex int `json:"channelIndex"`
	// LastFiredAt is when the most recent dispatch attempt was made.
	// +optional
	LastFiredAt *metav1.Time `json:"lastFiredAt,omitempty"`
	// LastEvent is the event type that triggered the most recent dispatch.
	// +optional
	LastEvent NotifyEvent `json:"lastEvent,omitempty"`
	// Succeeded is false when all retry attempts failed.
	Succeeded bool `json:"succeeded"`
	// Error is the last error message when Succeeded is false.
	// +optional
	Error string `json:"error,omitempty"`
}

type NotifyEvent string

type ProbeType string

type PromptFragment struct {
	// Name identifies this fragment. Must be unique within the ArkSettings object.
	// Used for override resolution when the same name appears in multiple settings.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Name string `json:"name"`

	// Text is the fragment content. May be multi-line.
	// +kubebuilder:validation:Required
	Text string `json:"text"`

	// Position controls where this fragment is injected relative to the agent's systemPrompt.
	//   prepend — inserted before systemPrompt (persona, context, constraints)
	//   append  — inserted after systemPrompt (output rules, closing instructions)
	// +kubebuilder:validation:Enum=prepend;append
	// +kubebuilder:default=append
	Position string `json:"position,omitempty"`
}

type PromptFragments struct {
	// Persona is a persona/role description prepended to the system prompt.
	// Deprecated: define a PromptFragment with position=prepend instead.
	Persona string `json:"persona,omitempty"`
	// OutputRules defines output format constraints appended to the system prompt.
	// Deprecated: define a PromptFragment with position=append instead.
	OutputRules string `json:"outputRules,omitempty"`
}

type RedisMemoryConfig struct {
	// SecretRef names a Secret whose REDIS_URL key is injected into agent pods.
	SecretRef LocalObjectReference `json:"secretRef"`

	// TTLSeconds is how long memory entries are retained. 0 means no expiry.
	// +kubebuilder:default=3600
	TTLSeconds int `json:"ttlSeconds,omitempty"`

	// MaxEntries caps the number of stored entries per agent instance. 0 means unlimited.
	MaxEntries int `json:"maxEntries,omitempty"`
}

type RegistryLookupSpec struct {
	// Capability is the exact capability ID to match.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Capability string `json:"capability"`
	// Tags narrows candidates to agents that declare ALL listed tags.
	// +optional
	Tags []string `json:"tags,omitempty"`
	// Strategy controls which agent is selected when multiple match.
	// +kubebuilder:default=least-busy
	Strategy RegistryLookupStrategy `json:"strategy,omitempty"`
	// RegistryRef names the ArkRegistry to query. Defaults to first registry in namespace.
	// +optional
	RegistryRef *LocalObjectReference `json:"registryRef,omitempty"`
	// Fallback is the role/agent name to use when no agent matches.
	// If unset and no match, the step fails with RegistryLookupFailed.
	// +optional
	Fallback string `json:"fallback,omitempty"`
}

type RegistryLookupStrategy string

type RegistryScope string

type SlackChannelSpec struct {
	// WebhookURLFrom reads the Slack incoming webhook URL from a Secret key.
	WebhookURLFrom corev1.SecretKeySelector `json:"webhookURLFrom"`
}

type StepValidation struct {
	// Contains is a RE2 regular expression that must match somewhere in the step output.
	// Avoid anchoring on multi-byte characters (e.g. emoji) — use substring match instead.
	// +optional
	Contains string `json:"contains,omitempty"`

	// Schema is a JSON Schema string. The step output must be valid JSON that satisfies
	// the schema's required fields and top-level property type constraints.
	// +optional
	Schema string `json:"schema,omitempty"`

	// Semantic is a natural-language validator prompt sent to an LLM.
	// The LLM must respond with "PASS" (case-insensitive) for validation to pass.
	// Use {{ .output }} in the prompt to embed the step output.
	// +optional
	Semantic string `json:"semantic,omitempty"`

	// SemanticModel overrides the LLM model used for semantic validation.
	// Defaults to the step's ArkAgent model when empty.
	// Recommended: use a stronger model than the step agent to avoid grading its own output.
	// +optional
	SemanticModel string `json:"semanticModel,omitempty"`

	// OnFailure controls what happens when validation fails.
	// "fail" (default) marks the step Failed immediately.
	// "retry" resets the step to Pending for re-execution.
	// +kubebuilder:default=fail
	// +kubebuilder:validation:Enum=fail;retry
	// +optional
	OnFailure string `json:"onFailure,omitempty"`

	// MaxRetries caps validation-level retries when OnFailure is "retry".
	// Independent of queue-level task retries.
	// +kubebuilder:default=2
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:Maximum=10
	// +optional
	MaxRetries int `json:"maxRetries,omitempty"`

	// RejectPatterns is a list of RE2 regular expressions that act as a security gate
	// against prompt injection. A match against any pattern causes the step to fail
	// immediately with reason OutputRejected, regardless of other validation settings.
	// Evaluated before Contains, Schema, and Semantic checks.
	// Example: ["(?i)ignore.*previous.*instructions", "(?i)act as"]
	// +optional
	RejectPatterns []string `json:"rejectPatterns,omitempty"`
}

type SystemPromptSource struct {
	// ConfigMapKeyRef selects a key of a ConfigMap in the same namespace.
	// +optional
	ConfigMapKeyRef *corev1.ConfigMapKeySelector `json:"configMapKeyRef,omitempty"`
	// SecretKeyRef selects a key of a Secret in the same namespace.
	// Use this when the prompt contains sensitive instructions.
	// +optional
	SecretKeyRef *corev1.SecretKeySelector `json:"secretKeyRef,omitempty"`
}

type TeamOutputSource struct {
	// Name is the ArkTeam to watch.
	// +kubebuilder:validation:Required
	Name string `json:"name"`

	// OnPhase is the team phase that fires the trigger. Defaults to Succeeded.
	// +kubebuilder:default=Succeeded
	OnPhase ArkTeamPhase `json:"onPhase,omitempty"`
}

type TokenUsage struct {
	// InputTokens is the total number of prompt/input tokens sent to the LLM.
	InputTokens int64 `json:"inputTokens"`
	// OutputTokens is the total number of completion/output tokens generated by the LLM.
	OutputTokens int64 `json:"outputTokens"`
	// TotalTokens is InputTokens + OutputTokens, provided for convenient display.
	TotalTokens int64 `json:"totalTokens"`
}

type TriggerSourceType string

type VectorStoreMemoryConfig struct {
	// Provider is the vector database to use.
	Provider VectorStoreProvider `json:"provider"`

	// Endpoint is the base URL of the vector database (e.g. "http://qdrant:6333").
	// +kubebuilder:validation:Required
	Endpoint string `json:"endpoint"`

	// Collection is the collection/index name to store memories in.
	// +kubebuilder:default=agent-memories
	Collection string `json:"collection,omitempty"`

	// SecretRef optionally names a Secret whose VECTOR_STORE_API_KEY is injected into agent pods.
	SecretRef *LocalObjectReference `json:"secretRef,omitempty"`

	// TTLSeconds is how long memory entries are retained. 0 means no expiry.
	TTLSeconds int `json:"ttlSeconds,omitempty"`
}

type VectorStoreProvider string

type WebhookChannelSpec struct {
	// URL is the webhook endpoint as a literal string.
	// +optional
	URL string `json:"url,omitempty"`
	// URLFrom reads the URL from a Secret key. Takes precedence over URL.
	// +optional
	URLFrom *corev1.SecretKeySelector `json:"urlFrom,omitempty"`
	// Method is the HTTP method. Defaults to POST.
	// +kubebuilder:default=POST
	// +kubebuilder:validation:Enum=GET;POST;PUT;PATCH
	Method string `json:"method,omitempty"`
	// Headers are additional HTTP headers included in every request.
	// +optional
	Headers []WebhookHeader `json:"headers,omitempty"`
}

type WebhookHeader struct {
	// Name is the HTTP header name.
	Name string `json:"name"`
	// Value is the literal header value.
	// +optional
	Value string `json:"value,omitempty"`
	// ValueFrom reads the header value from a Secret key.
	// +optional
	ValueFrom *corev1.SecretKeySelector `json:"valueFrom,omitempty"`
}

type WebhookToolSpec struct {
	// Name is the tool identifier exposed to the LLM. Must be unique within the deployment.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Name string `json:"name"`
	// Description explains the tool's purpose to the LLM.
	Description string `json:"description,omitempty"`
	// URL is the HTTP endpoint the agent calls when the LLM invokes this tool.
	// +kubebuilder:validation:Required
	URL string `json:"url"`
	// Method is the HTTP method used when calling the endpoint.
	// +kubebuilder:default=POST
	// +kubebuilder:validation:Enum=GET;POST;PUT;PATCH
	Method string `json:"method,omitempty"`
	// InputSchema is a JSON Schema object (as a raw JSON string) describing the tool's
	// input parameters. The LLM uses this to construct valid inputs.
	InputSchema string `json:"inputSchema,omitempty"`
}