v1alpha1

type APIKeyAuth struct {
	// SecretKeyRef references the Secret containing the API key.
	SecretKeyRef SecretKeyRef `json:"secretKeyRef"`
	// HeaderName is the HTTP header name. Defaults to "X-API-Key".
	// +kubebuilder:default="X-API-Key"
	// +optional
	HeaderName string `json:"headerName,omitempty"`
}

type AWSAuthSpec struct {
	// RoleARN is the AWS IAM Role ARN to assume.
	// Example: "arn:aws:iam::123456789012:role/my-agent-role"
	RoleARN string `json:"roleArn"`
}

type AdaptivePolicy struct {
	// MaxDynamicSteps caps the total number of dynamically-added steps.
	// +kubebuilder:validation:Minimum=1
	MaxDynamicSteps int `json:"maxDynamicSteps"`

	// AllowedAgentRefs restricts which Agent CRDs can be proposed.
	// If empty, any agent in the namespace may be proposed.
	// +optional
	AllowedAgentRefs []string `json:"allowedAgentRefs,omitempty"`

	// AllowLoops permits re-running a step with refined input.
	// +optional
	AllowLoops bool `json:"allowLoops,omitempty"`

	// MaxLoopIterations caps loop retries per step. Defaults to 3.
	// +kubebuilder:default=3
	// +optional
	MaxLoopIterations int `json:"maxLoopIterations,omitempty"`

	// RequireApprovalForUnlisted pauses the workflow and requests human approval
	// when an agent proposes a step using an agent not in AllowedAgentRefs.
	// If false, such proposals are auto-rejected.
	// +optional
	RequireApprovalForUnlisted bool `json:"requireApprovalForUnlisted,omitempty"`
}

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

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

	Spec   AgentSpec   `json:"spec,omitempty"`
	Status AgentStatus `json:"status,omitempty"`
}

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

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

	Spec   AgentDeploymentSpec   `json:"spec,omitempty"`
	Status AgentDeploymentStatus `json:"status,omitempty"`
}

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

type AgentDeploymentPhase string

type AgentDeploymentSpec struct {
	// AgentRef names the Agent template to run continuously.
	// +kubebuilder:validation:MinLength=1
	AgentRef string `json:"agentRef"`

	// InputSource configures where this deployment receives input from.
	// +optional
	InputSource *InputSourceConfig `json:"inputSource,omitempty"`

	// RestartPolicy controls failure recovery and backoff behavior.
	// +optional
	RestartPolicy *DeploymentRestartPolicy `json:"restartPolicy,omitempty"`

	// ToolExecutionTimeoutSec is the per-tool-call ceiling (seconds) applied to every
	// AgentRun spawned from this deployment and to warm pods claimed by it. It feeds
	// RouterSafeguards.ToolExecutionTimeoutSec. Defaults to the model-router's 60s when
	// 0. Set high for long-holding tooling that exceeds the default (e.g. Sliver
	// interactive sessions, shells, pivot relays): 1800–3600. A 0 value preserves
	// today's 60s behaviour.
	// +kubebuilder:default=0
	// +optional
	ToolExecutionTimeoutSec int `json:"toolExecutionTimeoutSec,omitempty"`

	// MaxToolResultTokens overrides the per-tool-result token cap for this deployment.
	// 0 (default) = the operator computes a context-window-aware cap (~10% of the
	// model's ContextWindow, floored at 8000 and capped at 64000 tokens, and never more
	// than half of MaxRequestTokens so a single result can't by itself blow the
	// request budget) so large MCP/file/commit-patch results are not silently
	// truncated. Eyeballed against the loudest offender: router.go is ~153K chars
	// (~38k tokens) on the 1M-context poolside model — the default 64k cap reads it
	// in full. Raise further for agents that routinely read very large files, or lower
	// for spend-thrifty agents.
	// +optional
	MaxToolResultTokens int `json:"maxToolResultTokens,omitempty"`

	// Safeguards configures behavioral loop guards (MaxRepeatedToolCalls,
	// MaxConsecutiveNoopTurns, ToolFrequencyCap, etc.) for runs spawned from this
	// deployment. Omit to use the operator's conservative defaults; set any field to 0
	// to keep the default for that field. Fields that are left zero (defaulted) only
	// trip on genuine stuck loops and do NOT block legitimate repeated tool use
	// (MaxRepeatedToolCalls keys on identical tool+args, so reading many distinct
	// files — e.g. a PR review — never trips it). Reuses the AgentRunSafeguards shape.
	// +optional
	Safeguards *AgentRunSafeguards `json:"safeguards,omitempty"`

	// Replicas is the desired number of agent pod replicas. Defaults to 1.
	// +kubebuilder:default=1
	// +optional
	Replicas *int32 `json:"replicas,omitempty"`

	// CheckpointTTL is the duration to retain conversation checkpoints after completion.
	// Defaults to 2592000 (30 days).
	// +kubebuilder:default=2592000
	// +optional
	CheckpointTTL int `json:"checkpointTTL,omitempty"`

	// WarmPoolSize is the number of pre-warmed pods to maintain for fast run dispatch.
	// Warm pods have the agent and model-router already initialized, eliminating cold-start
	// latency (~15s) for chat runs. Set to 0 to disable (use classic per-run pods).
	// +kubebuilder:default=1
	// +optional
	WarmPoolSize int `json:"warmPoolSize,omitempty"`

	// MaxRequestsPerPod caps how many requests a warm pod will serve before it is
	// recycled (deleted and replaced). 0 (default) means warm pods are REUSED across
	// requests — after a run completes the pod is returned to the idle pool instead of
	// being killed, and is re-claimed for the next chat run. Age-based recycling is
	// disabled by default (see WarmPodMaxAge), so reuse is the normal path.
	//
	// Set >0 (e.g. 50) to rotate pods after that many served requests, which can be
	// useful to shed per-request state or refresh long-running connections.
	// +kubebuilder:default=0
	// +optional
	MaxRequestsPerPod int `json:"maxRequestsPerPod,omitempty"`

	// WarmPodMaxAge is the maximum age of a warm pod before it is recycled
	// (deleted and replaced). It defaults to 0 (indefinite) when unset: warm pods
	// then persist until manually deleted, the agent process exits, config-drift
	// recycle fires (see RecycleOnConfigDrift), or the MaxRequestsPerPod cap is hit.
	// This is the desired default for chat and long-trajectory workloads, where
	// pods must stay alive across runs so an in-progress session is never torn down
	// mid-task. When age recycling is disabled a long-lived SA token (the cluster
	// maximum) is minted for each pod so it can keep authenticating claim-run
	// POSTs for its entire life.
	//
	// Set this to a positive duration explicitly to OPT IN to age-based recycling,
	// e.g. 50m to recycle pods roughly once per LLM token budget window. (controller-gen
	// cannot express a duration default here, so 0 is applied in code.)
	// +optional
	WarmPodMaxAge *metav1.Duration `json:"warmPodMaxAge,omitempty"`

	// RecycleOnConfigDrift controls whether warm pods are recycled when the
	// router config changes (agent spec, providers/weights, tools, KBs,
	// guardrails). Defaults to true: a config change rolls the warm pool so
	// pods pick up the new config immediately.
	//
	// Set to false to keep warm pods alive across config changes. Pods continue
	// serving from the router-config snapshot they were created with and only
	// refresh on their next natural recycle (age cap or process exit). Combining
	// "WarmPodMaxAge: 0" with "RecycleOnConfigDrift: false" keeps warm pods
	// until they are manually deleted (or the agent process exits).
	// +kubebuilder:default=true
	// +optional
	RecycleOnConfigDrift *bool `json:"recycleOnConfigDrift,omitempty"`

	// WarmLocalCache controls the per-warm-pod local disk cache (an emptyDir) that
	// supplements the shared Redis state store. The model-router write-throughs each
	// checkpoint to the local disk AND to Redis, then reads from the local disk first
	// (falling back to Redis on a local miss). Because warm pods are reused across
	// chat runs (the same Pod survives multiple claims until recycled), the local
	// cache accelerates warm-pod resume (no Redis round-trip to hydrate the prior
	// conversation) and lets a warm pod keep serving if Redis is transiently
	// unavailable. The local cache is per-Pod only — it is wiped when the warm pod is
	// recycled/deleted; Redis remains the durable, cross-pod source of truth.
	//
	// Note: this is unrelated to the read-only-rootFilesystem emptyDir at /tmp
	// (which is scratch space for the restricted pod-security profile); this is a
	// separate disk-backed volume used to mirror checkpoints.
	//
	// Defaults to true when WarmPoolSize > 0 (a warm pool), false otherwise.
	// +optional
	WarmLocalCache *bool `json:"warmLocalCache,omitempty"`

	// WarmLocalCacheSizeMi is the SizeLimit (in Mi) for each warm pod's local cache
	// emptyDir. 0 means unlimited (bounded only by node ephemeral storage).
	// Defaults to 256.
	// +kubebuilder:default=256
	// +optional
	WarmLocalCacheSizeMi int `json:"warmLocalCacheSizeMi,omitempty"`

	// WebhookNotify configures the optional Slack incoming-webhook integration. When set,
	// warm pods mount the referenced Secret's webhook URL as WEBHOOK_URL into the
	// model-router sidecar, which exposes the _webhook_notify builtin tool. The webhook
	// URL is the credential (no per-user OAuth); it posts to the configured channel.
	// +optional
	WebhookNotify *WebhookNotifyConfig `json:"webhookNotify,omitempty"`
}

type AgentDeploymentStatus struct {
	// Phase is the current lifecycle phase of the deployment.
	// +optional
	Phase AgentDeploymentPhase `json:"phase,omitempty"`

	// ReadyReplicas is the number of ready agent pods.
	// +optional
	ReadyReplicas int32 `json:"readyReplicas,omitempty"`

	// AvailableReplicas is the number of available agent pods.
	// +optional
	AvailableReplicas int32 `json:"availableReplicas,omitempty"`

	// LastUpdateTime is when the deployment was last reconciled.
	// +optional
	LastUpdateTime *metav1.Time `json:"lastUpdateTime,omitempty"`

	// LastFailureTime is when the last pod failure occurred.
	// +optional
	LastFailureTime *metav1.Time `json:"lastFailureTime,omitempty"`

	// ConsecutiveFailures is the count of consecutive pod failures.
	// Resets to 0 when a pod succeeds.
	// +optional
	ConsecutiveFailures int `json:"consecutiveFailures,omitempty"`

	// PodNames lists the names of managed agent pods.
	// +optional
	PodNames []string `json:"podNames,omitempty"`

	// WarmPoolReady is the number of idle warm pods ready to accept runs.
	// +optional
	WarmPoolReady int `json:"warmPoolReady,omitempty"`

	// WarmPoolLastRecycleReason is the reason the most recent warm pod was
	// recycled (token-age-expired, stale-config, terminal-phase,
	// request-cap-<N>), or empty if no warm pod has been recycled yet. Emitted
	// as a WarmPodRecycled Kubernetes Event on the deployment as well.
	// +optional
	WarmPoolLastRecycleReason string `json:"warmPoolLastRecycleReason,omitempty"`

	// WarmPoolLastRecycleAt is when the most recent warm pod was recycled.
	// +optional
	WarmPoolLastRecycleAt *metav1.Time `json:"warmPoolLastRecycleAt,omitempty"`

	// Message contains a human-readable status message.
	// +optional
	Message string `json:"message,omitempty"`

	// ContextUsedTokens is the estimated token count of the current conversation context.
	// Only populated when running in chat mode.
	// +optional
	ContextUsedTokens int `json:"contextUsedTokens,omitempty"`

	// MaxContextTokens is the maximum context window size for the selected model.
	// +optional
	MaxContextTokens int `json:"maxContextTokens,omitempty"`

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

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

type AgentMemoryConfig struct {
	// CheckpointEvery controls how often (in LLM turns) the model-router writes a checkpoint.
	// 1 means every turn. Higher values reduce storage writes but increase recovery loss window.
	// +kubebuilder:default=1
	// +optional
	CheckpointEvery int `json:"checkpointEvery,omitempty"`

	// ResumeWindowSeconds is how long to retain state after a failure for pod restart/resume.
	// Defaults to 3600 (1 hour).
	// +kubebuilder:default=3600
	// +optional
	ResumeWindowSeconds int `json:"resumeWindowSeconds,omitempty"`

	// ArchiveOnCompletion, when true, promotes state to object storage when the run succeeds.
	// +kubebuilder:default=false
	// +optional
	ArchiveOnCompletion bool `json:"archiveOnCompletion,omitempty"`

	// EpisodicSummaryEvery summarizes the conversation every N LLM turns and injects
	// the summary as context, keeping the active context window compact.
	// 0 disables episodic memory.
	// +optional
	EpisodicSummaryEvery int `json:"episodicSummaryEvery,omitempty"`

	// SummaryModelSelectorRef names the ModelSelector used for summarization calls.
	// Defaults to the agent's own ModelSelectorRef when unset.
	// +optional
	SummaryModelSelectorRef string `json:"summaryModelSelectorRef,omitempty"`

	// LongTermMemoryRef names a KnowledgeBase (same namespace) used as persistent
	// long-term memory. The model-router automatically retrieves semantically relevant
	// memories before each turn and exposes a _memory_store tool so the agent can
	// explicitly persist facts across sessions.
	// If the KnowledgeBase is not Ready, the run proceeds without long-term memory
	// and a MemoryUnavailable event is emitted.
	// +optional
	LongTermMemoryRef string `json:"longTermMemoryRef,omitempty"`

	// Hindsight configures the hindsight memory system integration.
	// When enabled, the model-router will recall relevant memories before each
	// LLM call and retain the conversation after each turn.
	// +optional
	Hindsight *HindsightMemoryConfig `json:"hindsight,omitempty"`
}

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

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

	Spec   AgentRunSpec   `json:"spec,omitempty"`
	Status AgentRunStatus `json:"status,omitempty"`
}

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

type AgentRunPhase string

type AgentRunRestartPolicy struct {
	// MaxRetries is the number of times to restart a failed pod before marking the run Failed.
	// +kubebuilder:default=3
	// +optional
	MaxRetries int `json:"maxRetries,omitempty"`
}

type AgentRunSafeguards struct {
	// MaxConsecutiveNoopTurns halts the run if the LLM produces this many consecutive
	// turns with no tool calls and fewer than MinSubstantiveTokens output tokens.
	// 0 disables the check.
	// +optional
	MaxConsecutiveNoopTurns int `json:"maxConsecutiveNoopTurns,omitempty"`

	// MinSubstantiveTokens is the minimum number of output tokens required for a turn
	// to count as substantive. Only evaluated when MaxConsecutiveNoopTurns > 0.
	// +kubebuilder:default=20
	// +optional
	MinSubstantiveTokens int `json:"minSubstantiveTokens,omitempty"`

	// MaxRepeatedToolCalls halts the run if the same tool is called with identical
	// arguments this many times within the run. 0 disables the check.
	// +optional
	MaxRepeatedToolCalls int `json:"maxRepeatedToolCalls,omitempty"`

	// ToolFrequencyCap halts the run if any single tool is called more than this many
	// times in total across the run. 0 disables the check.
	// +optional
	ToolFrequencyCap int `json:"toolFrequencyCap,omitempty"`

	// ToolExecutionTimeoutSec is the maximum number of seconds a single tool call may
	// take before it is cancelled and a structured error is returned to the LLM.
	// This prevents a hanging tool (e.g. blocking I/O, deadlock) from stalling the
	// entire run. Defaults to 60. 0 means use the default.
	// +kubebuilder:default=60
	// +optional
	ToolExecutionTimeoutSec int `json:"toolExecutionTimeoutSec,omitempty"`
}

type AgentRunSpec struct {
	// AgentRef names the Agent to run.
	// +kubebuilder:validation:MinLength=1
	AgentRef string `json:"agentRef"`

	// Input is the user task passed to the agent process via the AGENTORC_INPUT env var.
	// +kubebuilder:validation:MinLength=1
	Input string `json:"input"`

	// Timeout is the maximum duration for this run. Defaults to 5 minutes.
	// +optional
	Timeout *metav1.Duration `json:"timeout,omitempty"`

	// Callbacks configures webhooks invoked on run completion.
	// +optional
	Callbacks *CallbackConfig `json:"callbacks,omitempty"`

	// RestartPolicy controls failure recovery behaviour.
	// +optional
	RestartPolicy *AgentRunRestartPolicy `json:"restartPolicy,omitempty"`

	// ParentRunRef is the name of the parent AgentRun when this run was spawned
	// by an orchestrator agent via the agent-as-tool pattern.
	// Set automatically by the tool executor; do not set manually.
	// +optional
	ParentRunRef string `json:"parentRunRef,omitempty"`

	// PriorRunRef is the name of the previous AgentRun in this chat session.
	// When set, the model-router loads that run's accumulated message checkpoint as
	// the initial conversation history, enabling multi-turn context across runs.
	// Set automatically by the deployment chat API; do not set manually.
	// +optional
	PriorRunRef string `json:"priorRunRef,omitempty"`

	// Safeguards configures behavioral guardrails that halt the run when the agent
	// appears stuck in a loop or making no progress.
	// +optional
	Safeguards *AgentRunSafeguards `json:"safeguards,omitempty"`

	// Egress configures durable result delivery to an external message bus
	// (Kafka, Pub/Sub, or Redis stream) on terminal phase. When set, the
	// controller publishes the final TaskResponse to the configured sink.
	// Independent of webhook callbacks — both can be configured simultaneously.
	// +optional
	Egress *EgressConfig `json:"egress,omitempty"`
}

type AgentRunStatus struct {
	// Phase is the current lifecycle phase of this run.
	// +optional
	Phase AgentRunPhase `json:"phase,omitempty"`

	// PodName is the name of the agent pod for this run.
	// +optional
	PodName string `json:"podName,omitempty"`

	// RouterPodName is the name of the model-router pod when split-pod topology is active.
	// Empty when using the default combined-pod (sidecar) topology.
	// +optional
	RouterPodName string `json:"routerPodName,omitempty"`

	// StartTime is when the agent pod started.
	// +optional
	StartTime *metav1.Time `json:"startTime,omitempty"`

	// CompletionTime is when the run reached a terminal phase.
	// +optional
	CompletionTime *metav1.Time `json:"completionTime,omitempty"`

	// SpendUSD is the total USD spend for this run so far, updated periodically.
	// +optional
	SpendUSD string `json:"spendUSD,omitempty"`

	// Output is the agent's final output captured from pod stdout.
	// Truncated to 10KB; full output is in the checkpoint store.
	// +optional
	Output string `json:"output,omitempty"`

	// RawOutput is the raw pod stdout, useful for debugging.
	// Truncated to 4KB.
	// +optional
	RawOutput string `json:"rawOutput,omitempty"`

	// CheckpointRef is the storage key of the latest conversation checkpoint.
	// Used by the controller to resume a failed run.
	// +optional
	CheckpointRef string `json:"checkpointRef,omitempty"`

	// RestartCount is the number of times this run's pod has been restarted.
	// +optional
	RestartCount int `json:"restartCount,omitempty"`

	// LastRestartReason describes why the pod was last restarted.
	// +optional
	LastRestartReason string `json:"lastRestartReason,omitempty"`

	// ChildRunRefs lists the names of child AgentRuns spawned by this run.
	// +optional
	ChildRunRefs []string `json:"childRunRefs,omitempty"`

	// HandoffTarget is the Agent name this run handed off to, if Phase is HandedOff.
	// +optional
	HandoffTarget string `json:"handoffTarget,omitempty"`

	// ClarifyQuestion is the question posed to the human when Phase is WaitingForInput.
	// +optional
	ClarifyQuestion string `json:"clarifyQuestion,omitempty"`

	// ClarifyAnswer is the human's response, set via the UI API.
	// +optional
	ClarifyAnswer string `json:"clarifyAnswer,omitempty"`

	// WaitingSince records when the run entered WaitingForInput.
	// Used to enforce a waiting timeout separate from the run timeout.
	// +optional
	WaitingSince *metav1.Time `json:"waitingSince,omitempty"`

	// ContinuationRunRef is the name of the follow-up AgentRun created when
	// the human answers a clarifying question. The original run stays in
	// WaitingForInput (for audit) and the continuation carries the work forward.
	// +optional
	ContinuationRunRef string `json:"continuationRunRef,omitempty"`

	// LoopDetected is set when the run was halted by a safeguard trip.
	// The run phase will be Failed when this is set.
	// +optional
	LoopDetected *LoopDetectedInfo `json:"loopDetected,omitempty"`

	// FailureReason is a human-readable explanation of why the run failed,
	// set by the agent via the _fail built-in tool.
	// +optional
	FailureReason string `json:"failureReason,omitempty"`

	// InputMode mirrors Agent.spec.runtime.inputMode, cached here so the controller
	// does not need to re-fetch the Agent in handlePodSuccess.
	// +optional
	InputMode string `json:"inputMode,omitempty"`

	// EpisodicChunks is the number of episodic memory summaries generated during this run.
	// +optional
	EpisodicChunks int `json:"episodicChunks,omitempty"`

	// RoutingDecisions records the model routing decisions made during this run.
	// Populated by the controller from the resolved ModelSelector configuration
	// and updated by the model-router sidecar at runtime.
	// +optional
	RoutingDecisions []RoutingDecision `json:"routingDecisions,omitempty"`

	// ContextUsedTokens is the estimated token count of the conversation context.
	// Updated by the model-router at runtime and reflects the current size of the
	// accumulated message history.
	// +optional
	ContextUsedTokens int `json:"contextUsedTokens,omitempty"`

	// MaxContextTokens is the maximum context window size for the selected model.
	// Used to calculate how much context is available for the conversation.
	// +optional
	MaxContextTokens int `json:"maxContextTokens,omitempty"`

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

type AgentRuntime struct {
	// OCIRef is the OCI image reference for the agent process.
	// Must be signed with Cosign unless imageVerification.skip is set.
	// +kubebuilder:validation:MinLength=1
	OCIRef string `json:"ociRef"`

	// Framework hints to the operator which env var injection tier to use.
	// Supported values:
	//   openai-compatible  - inject OPENAI_BASE_URL + OPENAI_API_KEY (default)
	//   autogen            - inject OAI_CONFIG_LIST via init container
	//   semantic-kernel    - inject appsettings via init container
	//   langgraph          - openai-compatible + inject LANGGRAPH_CHECKPOINT_URL
	//   shim               - hosts-file shim for frameworks that hardcode their endpoint
	// +kubebuilder:validation:Enum=openai-compatible;autogen;semantic-kernel;langgraph;shim
	// +kubebuilder:default=openai-compatible
	// +optional
	Framework string `json:"framework,omitempty"`

	// ShimTarget is the hostname to intercept when Framework is "shim".
	// Example: "api.openai.com", "generativelanguage.googleapis.com"
	// +optional
	ShimTarget string `json:"shimTarget,omitempty"`

	// Command overrides the container entrypoint.
	// +optional
	Command []string `json:"command,omitempty"`

	// Args overrides the container command arguments.
	// +optional
	Args []string `json:"args,omitempty"`

	// InputMode controls how the operator delivers the run input to the agent.
	// env  - inject AGENTORC_INPUT env var (default)
	// http - POST the input as JSON to the agent's HTTP endpoint
	// +kubebuilder:validation:Enum=env;http
	// +optional
	InputMode string `json:"inputMode,omitempty"`

	// InputPort is the TCP port the agent's HTTP server listens on (http mode only).
	// Defaults to 8000.
	// +optional
	InputPort int `json:"inputPort,omitempty"`

	// InputPath is the HTTP path to POST the run input to (http mode only).
	// Defaults to /invoke.
	// +optional
	InputPath string `json:"inputPath,omitempty"`

	// SecurityContextOverride opts the agent container (only the "agent" container,
	// never the model-router sidecar) out of the default restricted PodSecurityStandard.
	//
	// Intended ONLY for purpose-built agents that require elevated privileges the
	// restricted baseline forbids — e.g. a red-team pwnbox that must bring up a VPN
	// tun device (requires NET_ADMIN + /dev/net/tun). When set, the operator mounts
	// /dev/net/tun into the agent container and applies the requested posture.
	//
	// Admission is gated by a validating webhook: the agent's namespace must carry the
	// label `agentorca.io/enable-privileged-pods: "true"` AND the Agent must reference a
	// GuardrailPolicyRef. These checks fail‑closed.
	// +optional
	SecurityContextOverride *PodSecurityOverride `json:"securityContextOverride,omitempty"`

	// SecretRefs lists Kubernetes Secrets to mount into the agent container as volumes
	// (or, if MountPath is empty, inject as env vars). Unlike Tool.spec.secretRefs —
	// which target the model-router sidecar / tool pods — these mount directly into the
	// agent container. Useful for agent containers that need an on-disk credential the
	// agent code reads directly, e.g. an HTB OpenVPN “.ovpn“ config mounted at
	// “/etc/htb“. Mounted read-only.
	// +optional
	SecretRefs []SecretMount `json:"secretRefs,omitempty"`
}

type AgentSpec struct {
	// ModelSelectorRef names the ModelSelector that routes LLM calls for this agent.
	// +kubebuilder:validation:MinLength=1
	ModelSelectorRef string `json:"modelSelectorRef"`

	// Tools is the list of Tool names (in the same namespace) available to this agent.
	// The model-router injects these as OpenAI function definitions for every run.
	// +optional
	Tools []string `json:"tools,omitempty"`

	// SystemPrompt is the system-level instruction prepended to every conversation.
	// Leave empty to use the agent's own system prompt.
	// +optional
	SystemPrompt string `json:"systemPrompt,omitempty"`

	// Runtime defines the OCI image used to run the agent process.
	// +kubebuilder:validation:Required
	Runtime AgentRuntime `json:"runtime"`

	// Memory configures conversation state persistence and failure recovery.
	// +optional
	Memory *AgentMemoryConfig `json:"memory,omitempty"`

	// Resources sets default CPU/memory limits for AgentRun pods.
	// +optional
	Resources *ResourceRequirements `json:"resources,omitempty"`

	// ServiceAccountRef references a pre-existing ServiceAccount to use for agent pods.
	// If unset, the operator creates and manages "agentorca-agent-<name>".
	// Use this when the SA already has cloud provider annotations (IRSA, Workload Identity).
	// +optional
	ServiceAccountRef *LocalObjectRef `json:"serviceAccountRef,omitempty"`

	// CloudAuth declares cloud-provider identity bindings.
	// The operator applies the appropriate SA annotations automatically.
	// +optional
	CloudAuth *CloudAuthSpec `json:"cloudAuth,omitempty"`

	// KnowledgeBases lists KnowledgeBase names (same namespace) available to this agent.
	// When non-empty, the model-router injects _rag_search and _rag_ingest as built-in tools.
	// For finer control (e.g. confirmRequired), use KnowledgeBaseRefs instead.
	// +optional
	KnowledgeBases []string `json:"knowledgeBases,omitempty"`

	// KnowledgeBaseRefs is the structured alternative to KnowledgeBases.
	// When set, KnowledgeBases is ignored. Each ref supports per-KB options
	// such as requiring user confirmation before ingesting fixes.
	// +optional
	KnowledgeBaseRefs []KnowledgeBaseRef `json:"knowledgeBaseRefs,omitempty"`

	// GuardrailPolicyRef names the GuardrailPolicy (same namespace) applied to this agent's
	// inputs and outputs. The model-router enforces the policy's filters on every LLM call.
	// +optional
	GuardrailPolicyRef string `json:"guardrailPolicyRef,omitempty"`

	// NetworkIsolation configures network-level isolation between the agent and model-router.
	// When SplitPod is enabled, the agent and model-router run in separate Kubernetes Pods
	// with distinct NetworkPolicies, providing network-level egress isolation that the
	// default single-pod sidecar topology cannot enforce (containers in a Pod share a
	// network namespace, so NetworkPolicy cannot differentiate them).
	// +optional
	NetworkIsolation *NetworkIsolationSpec `json:"networkIsolation,omitempty"`

	// DisableClarify prevents the auto-trigger clarify safety net from activating.
	// Use this for autonomous agents that should not block waiting for human input.
	// When true, the _clarify tool is still available but auto-detection is disabled.
	// +kubebuilder:default=false
	// +optional
	DisableClarify bool `json:"disableClarify,omitempty"`
}

type AgentStatus struct {
	// ServiceAccountName is the name of the stable SA managed by the operator.
	// +optional
	ServiceAccountName string `json:"serviceAccountName,omitempty"`

	// CloudProviderDetected is the cloud provider the operator detected at startup.
	// +optional
	CloudProviderDetected string `json:"cloudProviderDetected,omitempty"`

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

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

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

	Spec   AgentWorkflowSpec   `json:"spec,omitempty"`
	Status AgentWorkflowStatus `json:"status,omitempty"`
}

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

type AgentWorkflowPhase string

type AgentWorkflowSpec struct {
	// Description is an optional human-readable summary of the workflow's purpose.
	// +optional
	Description string `json:"description,omitempty"`

	// Steps defines the DAG of agent executions. Each step names its dependencies via
	// DependsOn; steps with no dependencies run immediately when the workflow starts.
	// +kubebuilder:validation:MinItems=1
	Steps []WorkflowStep `json:"steps"`

	// BudgetCap limits total USD spend across all steps combined.
	// +optional
	BudgetCap *WorkflowBudgetCap `json:"budgetCap,omitempty"`

	// Timeout is the wall-clock limit for the entire workflow.
	// Steps still running when this expires are failed.
	// +optional
	Timeout *metav1.Duration `json:"timeout,omitempty"`

	// OnStepFailure controls what happens when a step fails.
	// "stop" (default): mark the workflow Failed and do not start new steps.
	// "continue": mark the failed step Skipped and continue with dependents.
	// +kubebuilder:validation:Enum=stop;continue
	// +optional
	OnStepFailure string `json:"onStepFailure,omitempty"`

	// AdaptivePolicy enables agents to propose new steps at runtime.
	// If nil, all _propose_step calls are rejected.
	// +optional
	AdaptivePolicy *AdaptivePolicy `json:"adaptivePolicy,omitempty"`
}

type AgentWorkflowStatus struct {
	// Phase is the overall workflow lifecycle state.
	// +optional
	Phase AgentWorkflowPhase `json:"phase,omitempty"`

	// Steps holds per-step execution state, one entry per spec.steps entry.
	// +optional
	Steps []WorkflowStepStatus `json:"steps,omitempty"`

	// DynamicSteps holds steps added at runtime by agent proposals.
	// These are reconciled by the controller using the same scheduling logic as spec.steps.
	// +optional
	DynamicSteps []WorkflowStep `json:"dynamicSteps,omitempty"`

	// DynamicStepStatuses holds execution state for dynamic steps.
	// +optional
	DynamicStepStatuses []WorkflowStepStatus `json:"dynamicStepStatuses,omitempty"`

	// ProposalLog records all proposals (approved and rejected) for auditability.
	// +optional
	ProposalLog []StepProposal `json:"proposalLog,omitempty"`

	// TotalSpendUSD is the sum of SpendUSD across all step AgentRuns.
	// +optional
	TotalSpendUSD string `json:"totalSpendUSD,omitempty"`

	// StartTime is when the first step was launched.
	// +optional
	StartTime *metav1.Time `json:"startTime,omitempty"`

	// CompletionTime is when the workflow reached a terminal phase.
	// +optional
	CompletionTime *metav1.Time `json:"completionTime,omitempty"`

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

type AuthHeader struct {
	// Name is the HTTP header name (e.g., "Authorization", "X-Custom-Token").
	Name string `json:"name"`
	// SecretKeyRef references the Secret containing the header value.
	SecretKeyRef SecretKeyRef `json:"secretKeyRef"`
}

type AzureAuthSpec struct {
	// ClientID is the Azure Managed Identity client ID.
	ClientID string `json:"clientId"`
}

type BudgetCap struct {
	// PerRun is the maximum USD spend allowed for a single AgentRun.
	// When reached the router switches to the cheapest available model,
	// then returns an error if spending still exceeds the cap.
	// Example: "0.50"
	// +optional
	PerRun string `json:"perRun,omitempty"`

	// PerDay is the maximum USD spend across all runs per calendar day.
	// Example: "50.00"
	// +optional
	PerDay string `json:"perDay,omitempty"`
}

type CallbackConfig struct {
	// OnComplete is a URL that receives a POST when the run succeeds.
	// +optional
	OnComplete string `json:"onComplete,omitempty"`

	// OnFailed is a URL that receives a POST when the run fails.
	// +optional
	OnFailed string `json:"onFailed,omitempty"`
}

type Checkpoint struct {
	// SessionID is the unique session identifier (e.g., "user-42").
	SessionID string `json:"sessionId"`
	// Version is incremented with each message exchange.
	Version int `json:"version"`
	// ConversationHistory holds the full message transcript.
	ConversationHistory []ConversationMessage `json:"conversationHistory,omitempty"`
	// Metadata tracks stats about the conversation.
	Metadata CheckpointMetadata `json:"metadata,omitempty"`
	// LastRunRef is the name of the most recently created AgentRun in this session.
	// Used to chain conversation context across turns in an AgentDeployment chat session.
	// +optional
	LastRunRef string `json:"lastRunRef,omitempty"`
}

type CheckpointMetadata struct {
	// TotalMessages is the count of messages in the conversation.
	TotalMessages int `json:"totalMessages,omitempty"`
	// TotalTokens is the cumulative token usage across all messages.
	TotalTokens int `json:"totalTokens,omitempty"`
	// TotalCostUSD is the cumulative cost in USD.
	TotalCostUSD string `json:"totalCostUSD,omitempty"`
	// StartTime is when the session began.
	// +optional
	StartTime *metav1.Time `json:"startTime,omitempty"`
	// LastMessageTime is when the last message was added.
	// +optional
	LastMessageTime *metav1.Time `json:"lastMessageTime,omitempty"`
}

type CloudAuthSpec struct {
	// GCP configures GKE Workload Identity.
	// +optional
	GCP *GCPAuthSpec `json:"gcp,omitempty"`
	// AWS configures EKS IRSA (IAM Roles for Service Accounts).
	// +optional
	AWS *AWSAuthSpec `json:"aws,omitempty"`
	// Azure configures AKS Azure Workload Identity.
	// +optional
	Azure *AzureAuthSpec `json:"azure,omitempty"`
}

type ConversationMessage struct {
	// Role is "user" or "assistant".
	Role string `json:"role"`
	// Content is the message text.
	Content string `json:"content"`
	// TraceEntries is a JSON-encoded array of trace entries (tool calls, tool results, etc.)
	// captured during this assistant turn. Stored as a string to avoid deep-copy complexity.
	// +optional
	TraceEntries string `json:"traceEntries,omitempty"`
}

type DeploymentRestartPolicy struct {
	// MinBackoffSeconds is the minimum backoff duration after a failure. Defaults to 5.
	// +kubebuilder:default=5
	// +optional
	MinBackoffSeconds int `json:"minBackoffSeconds,omitempty"`

	// MaxBackoffSeconds is the maximum backoff duration after a failure. Defaults to 300.
	// +kubebuilder:default=300
	// +optional
	MaxBackoffSeconds int `json:"maxBackoffSeconds,omitempty"`

	// MaxConsecutiveFailures is the number of consecutive failures before pausing the deployment.
	// 0 means unlimited (always restart). Defaults to 10.
	// +kubebuilder:default=10
	// +optional
	MaxConsecutiveFailures int `json:"maxConsecutiveFailures,omitempty"`
}

type EgressConfig struct {
	// Type is the sink type: kafka, pubsub, or redis.
	// +kubebuilder:validation:Enum=kafka;pubsub;redis
	Type EgressSinkType `json:"type"`

	// Topic is the destination topic/queue/stream name.
	// For Kafka: the topic name. For Pub/Sub: the topic name. For Redis: the stream name.
	// +kubebuilder:validation:MinLength=1
	Topic string `json:"topic"`

	// Brokers is the list of broker addresses (kafka only).
	// Example: ["kafka:9092"]
	// +optional
	Brokers []string `json:"brokers,omitempty"`

	// ProjectID is the GCP project ID (pubsub only).
	// +optional
	ProjectID string `json:"projectID,omitempty"`

	// Address is the Redis connection address (redis only).
	// Example: "redis-master:6379"
	// +optional
	Address string `json:"address,omitempty"`

	// SecretRef references a Secret containing connection credentials.
	// The Secret must be in the same namespace as the AgentRun.
	// For Kafka: key "sasl-username" and "sasl-password" (or "tls-cert"/"tls-key").
	// For Pub/Sub: key "credentials" containing a service-account JSON blob.
	// For Redis: key "password".
	// +optional
	SecretRef *SecretKeyRef `json:"secretRef,omitempty"`

	// Key is the partition key for the published message (kafka only).
	// If empty, the run ID is used as the key.
	// +optional
	Key string `json:"key,omitempty"`
}

type EgressResult struct {
	// RunID is the AgentRun name.
	RunID string `json:"runId"`
	// Agent is the agent name that was invoked.
	Agent string `json:"agent"`
	// Phase is the terminal phase: "Succeeded" or "Failed".
	Phase string `json:"phase"`
	// Output is the agent's final output (truncated to 10KB).
	Output string `json:"output,omitempty"`
	// SpendUSD is the total cost for this run.
	SpendUSD string `json:"spendUSD,omitempty"`
	// FailureReason is set when the run failed.
	FailureReason string `json:"failureReason,omitempty"`
	// CompletedAt is the RFC3339 timestamp of terminal phase.
	CompletedAt string `json:"completedAt,omitempty"`
	// Metadata is the original task submission metadata.
	Metadata map[string]string `json:"metadata,omitempty"`
	// Tenant is the tenant name (for multi-tenant deployments).
	Tenant string `json:"tenant,omitempty"`
}

type EgressRule struct {
	// Host is the target hostname. Wildcards like "*.example.com" are supported.
	Host string `json:"host"`
	// Port is the target port.
	Port int32 `json:"port"`
	// Protocol defaults to TCP.
	// +optional
	// +kubebuilder:default=TCP
	Protocol string `json:"protocol,omitempty"`
}

type EgressSinkType string

type EmbeddingConfig struct {
	// ModelSelectorRef names the ModelSelector used for embedding calls.
	// The selected model must support the /v1/embeddings endpoint.
	// +kubebuilder:validation:MinLength=1
	ModelSelectorRef string `json:"modelSelectorRef"`

	// ChunkSize is the maximum token count per document chunk.
	// +kubebuilder:default=512
	// +optional
	ChunkSize int `json:"chunkSize,omitempty"`

	// ChunkOverlap is the token overlap between adjacent chunks.
	// +kubebuilder:default=64
	// +optional
	ChunkOverlap int `json:"chunkOverlap,omitempty"`
}

type EnvVar struct {
	// Name of the environment variable.
	Name string `json:"name"`
	// Value is a literal value. Ignored if ValueFrom is set.
	// +optional
	Value string `json:"value,omitempty"`
	// ValueFrom references an indirect source for the value.
	// +optional
	ValueFrom *EnvVarSource `json:"valueFrom,omitempty"`
}

type EnvVarSource struct {
	// SecretKeyRef selects a key from a Kubernetes Secret.
	// +optional
	SecretKeyRef *SecretKeyRef `json:"secretKeyRef,omitempty"`
}

type FederatedAuthConfig struct {
	// IssuerURL is the OIDC issuer URL (e.g. "https://acme.okta.com/oauth2/default").
	// agent-orca fetches the JWKS from this issuer to verify token signatures.
	// +kubebuilder:validation:MinLength=1
	IssuerURL string `json:"issuerURL"`

	// ClientID is the expected "aud" (audience) claim in the JWT for bearer tokens,
	// and the OAuth2 client ID used for the interactive login flow.
	// +kubebuilder:validation:MinLength=1
	ClientID string `json:"clientID"`

	// MatchClaim is the JWT claim used to identify this tenant (e.g. "org_id",
	// "tenant", or a GitHub-style "repository_owner"). When both MatchClaim and
	// MatchValue are omitted the tenant trusts *any* token validly signed by
	// IssuerURL with the expected ClientID audience (issuer-only / default-allow).
	// +optional
	// +kubebuilder:validation:MinLength=1
	MatchClaim string `json:"matchClaim,omitempty"`

	// MatchValue is the expected value of MatchClaim that maps to this tenant.
	// Required when MatchClaim is set; omit both for issuer-only trust.
	// +optional
	// +kubebuilder:validation:MinLength=1
	MatchValue string `json:"matchValue,omitempty"`

	// ClientSecretRef references the OAuth2 client_secret used for the interactive
	// login (authorization-code) flow. When the ref omits a namespace, the
	// operator looks it up in the tenant's first allowed namespace
	// (spec.allowedNamespaces[0]). Omit for bearer-only federation (no secret is
	// needed — verification uses the IdP's public JWKS).
	// +optional
	ClientSecretRef SecretKeyRef `json:"clientSecretRef,omitempty"`

	// RedirectURI is the callback URL registered with the IdP for the interactive
	// login flow. Omit for bearer-only federation.
	// +optional
	RedirectURI string `json:"redirectURI,omitempty"`

	// ClaimMappings selects which IdP claims map onto the resolved principal/identity.
	// All fields default to the standard OIDC claim when empty (userid=sub,
	// groups=groups, email=email). Set userid=email for Google social login.
	// +optional
	ClaimMappings FederatedClaimMappings `json:"claimMappings,omitempty"`

	// Scopes configures the OAuth2 scopes requested during the interactive
	// (authorization-code) login flow. When omitted, defaults to
	// ["openid","email","profile"]. Some IdPs require additional scopes — notably
	// "offline_access" to receive a refresh token (so the session can be renewed
	// without re-prompting for credentials). Has no effect on bearer-only
	// federation: agent-orca verifies caller-presented JWTs against the IdP's
	// JWKS regardless of scopes.
	// +optional
	Scopes []string `json:"scopes,omitempty"`
}

type FederatedClaimMappings struct {
	// UserID maps to TenantIdentity.UserID (default "sub").
	// +optional
	UserID string `json:"userid,omitempty"`
	// Groups maps to TenantIdentity.Groups (default "groups").
	// +optional
	Groups string `json:"groups,omitempty"`
	// Email maps to TenantIdentity.Email (default "email").
	// +optional
	Email string `json:"email,omitempty"`
}

type FormatValidation struct {
	// JSONSchema is a JSON Schema document that the agent's final output must conform to.
	// +optional
	JSONSchema string `json:"jsonSchema,omitempty"`

	// MaxTokens limits the maximum output token count.
	// +optional
	MaxTokens int `json:"maxTokens,omitempty"`
}

type GCPAuthSpec struct {
	// ServiceAccount is the GCP Service Account email to impersonate.
	// Example: "my-agent@myproject.iam.gserviceaccount.com"
	ServiceAccount string `json:"serviceAccount"`
}

type GuardrailFilter struct {
	// Name is a human-readable identifier for this filter (used in logs and events).
	// +kubebuilder:validation:MinLength=1
	Name string `json:"name"`

	// Type selects the filter implementation.
	// +kubebuilder:validation:Enum=regex;keyword-blocklist;topic-validation
	Type string `json:"type"`

	// Action determines what happens when the filter matches.
	// "redact" replaces matched content with the replacement string.
	// "block" rejects the entire message and returns blockMessage to the caller.
	// "warn" logs a warning event but allows the message through.
	// +kubebuilder:validation:Enum=redact;block;warn
	Action string `json:"action"`

	// Patterns are regex-based match rules. Used when Type is "regex".
	// +optional
	Patterns []RegexPattern `json:"patterns,omitempty"`

	// Keywords configures keyword blocklist matching. Used when Type is "keyword-blocklist".
	// +optional
	Keywords *KeywordConfig `json:"keywords,omitempty"`

	// AllowedTopics restricts responses to these topics. Used when Type is "topic-validation".
	// +optional
	AllowedTopics []string `json:"allowedTopics,omitempty"`

	// BlockMessage is the message returned to the caller when Action is "block".
	// +optional
	BlockMessage string `json:"blockMessage,omitempty"`
}

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

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

	Spec   GuardrailPolicySpec   `json:"spec,omitempty"`
	Status GuardrailPolicyStatus `json:"status,omitempty"`
}

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

type GuardrailPolicySpec struct {
	// OutputFilters are applied to LLM responses before they reach the agent/caller.
	// Filters are evaluated in order; the first "block" action stops processing.
	// +optional
	OutputFilters []GuardrailFilter `json:"outputFilters,omitempty"`

	// InputFilters are applied to user messages before they reach the LLM.
	// +optional
	InputFilters []GuardrailFilter `json:"inputFilters,omitempty"`

	// FormatValidation enforces structural constraints on the final agent output.
	// +optional
	FormatValidation *FormatValidation `json:"formatValidation,omitempty"`
}

type GuardrailPolicyStatus struct {
	// Ready indicates the policy has been validated and can be enforced.
	// +optional
	Ready bool `json:"ready,omitempty"`

	// Message contains a human-readable status message.
	// +optional
	Message string `json:"message,omitempty"`

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

type HindsightMemoryConfig struct {
	// Enabled is true when hindsight is active.
	// +kubebuilder:default=true
	// +optional
	Enabled bool `json:"enabled,omitempty"`
	// URL is the hindsight API endpoint (e.g. http://hindsight.hindsight.svc.cluster.local:8888).
	// +optional
	URL string `json:"url,omitempty"`
	// BankIDTemplate is the template for the hindsight bank ID.
	// Can use placeholders like {namespace}, {runName}, {agentName} which will be replaced at runtime.
	// +optional
	BankIDTemplate string `json:"bankIdTemplate,omitempty"`
	// RecallBudget is the maximum number of memories to retrieve per turn.
	// +kubebuilder:default=5
	// +optional
	RecallBudget int `json:"recallBudget,omitempty"`
	// RetainOnEveryTurn is true to retain conversation after every LLM turn.
	// +kubebuilder:default=true
	// +optional
	RetainOnEveryTurn bool `json:"retainOnEveryTurn,omitempty"`
}

type IngestionBreakerState struct {
	// Failures counts consecutive failed runs of this source's ingestion Job.
	// Reset to zero when that Job succeeds. Drives the exponential
	// re-ingestion backoff so a persistently failing source cannot restart
	// Jobs in a tight loop and burn through API budgets.
	// +optional
	Failures int `json:"failures,omitempty"`

	// NextAttempt is the earliest time the controller will launch a new
	// ingestion Job for this source after a failure. After provider
	// daily-quota exhaustion this is set to the provider's quota reset time
	// rather than a short backoff.
	// +optional
	NextAttempt *metav1.Time `json:"nextAttempt,omitempty"`

	// Reason explains why this source's ingestion is paused (e.g.
	// "embedding provider daily quota exhausted; waiting for quota reset").
	// Empty when the source's ingestion is healthy.
	// +optional
	Reason string `json:"reason,omitempty"`
}

type IngestionConfig struct {
	// ConfigMapRefs lists ConfigMaps whose data keys are treated as documents.
	// +optional
	ConfigMapRefs []LocalObjectRef `json:"configMapRefs,omitempty"`

	// URLs lists HTTP(S) endpoints to fetch and ingest as documents.
	// +optional
	URLs []string `json:"urls,omitempty"`

	// S3 configures S3-compatible object storage as a document source.
	// +optional
	S3 *S3IngestionSource `json:"s3,omitempty"`

	// MCP lists MCP servers to fetch documents from via Kubernetes Jobs.
	// Each entry launches a Job that connects to the referenced MCPServer,
	// runs an optional discover step to enumerate items, then fetches each
	// item. Results are written to a ConfigMap and ingested by the controller.
	// +optional
	MCP []MCPIngestionSource `json:"mcp,omitempty"`

	// SyncIntervalSeconds re-ingests sources on a schedule. 0 means one-shot.
	// +kubebuilder:default=0
	// +optional
	SyncIntervalSeconds int `json:"syncIntervalSeconds,omitempty"`

	// NetworkEgress defines additional outbound network rules for ingestion
	// Job pods. The operator always creates a NetworkPolicy for ingestion Jobs
	// allowing DNS, the Kubernetes API, same-namespace services (Qdrant, MCP
	// servers, in-cluster embedding providers), and HTTP/HTTPS egress; these
	// rules are added to that allowlist (e.g. S3 on a custom port).
	// +optional
	NetworkEgress []EgressRule `json:"networkEgress,omitempty"`
}

type InputSourceConfig struct {
	// Type specifies the input source: chat (API-driven), queue (Redis, etc), pubsub (Kafka, etc), or loop (self-managed).
	// +kubebuilder:default=chat
	// +optional
	Type InputSourceType `json:"type,omitempty"`

	// Config holds provider-specific settings.
	// Examples:
	//   queue: {provider: "redis", url: "redis://redis:6379", queue: "tasks"}
	//   pubsub: {provider: "kafka", brokers: "kafka:9092", topic: "agent-input"}
	//   loop: {initialPrompt: "Run continuously, answering questions..."}
	// +optional
	Config map[string]string `json:"config,omitempty"`
}

type InputSourceType string

type IssuedAuthConfig struct {
	// ClientID is the OAuth2 client identifier for this tenant.
	// +kubebuilder:validation:MinLength=1
	ClientID string `json:"clientID"`

	// ClientSecretRef references the Kubernetes Secret containing the client secret.
	// The operator reads this to validate client_credentials requests.
	ClientSecretRef SecretKeyRef `json:"clientSecretRef"`
}

type ItemFilterConfig struct {
	// Key is the JSON field name to check (e.g. "type").
	// +kubebuilder:validation:MinLength=1
	Key string `json:"key"`

	// Value is the required value for the field (e.g. "file").
	// Objects where the field does not equal this value are excluded.
	// +kubebuilder:validation:MinLength=1
	Value string `json:"value"`
}

type KeywordConfig struct {
	// Inline is a list of keywords to block.
	// +optional
	Inline []string `json:"inline,omitempty"`

	// SecretRef references a Secret containing a newline-delimited keyword list.
	// +optional
	SecretRef *SecretKeyRef `json:"secretRef,omitempty"`
}

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

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

	Spec   KnowledgeBaseSpec   `json:"spec,omitempty"`
	Status KnowledgeBaseStatus `json:"status,omitempty"`
}

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

type KnowledgeBaseRef struct {
	// Name is the KnowledgeBase CR name (same namespace).
	// +kubebuilder:validation:MinLength=1
	Name string `json:"name"`

	// ConfirmRequired when true replaces the _rag_ingest tool with _propose_fix and
	// _confirm_fix for this knowledge base. Fixes are staged in Redis and only promoted
	// to the KnowledgeBase when the user explicitly confirms they worked.
	// +optional
	ConfirmRequired bool `json:"confirmRequired,omitempty"`
}

type KnowledgeBaseSpec struct {
	// Description is a human-readable summary of this knowledge base.
	// +optional
	Description string `json:"description,omitempty"`

	// AllowedAgents is the explicit list of Agent names (in the same namespace) that are
	// permitted to use this KnowledgeBase. When set to a non-nil list, only the named
	// agents may access this KnowledgeBase. When omitted (nil), access is unrestricted
	// (backward-compatible default for existing KnowledgeBases).
	//
	// To explicitly deny all agents, set this to an empty list: allowedAgents: [].
	//
	// The operator enforces this at AgentRun/AgentDeployment creation time.
	// At runtime, the operator API verifies the calling agent's identity via
	// TokenReview and rejects requests from agents not in this list.
	// +optional
	AllowedAgents []string `json:"allowedAgents,omitempty"`

	// VectorStore configures the backing vector database.
	// +optional
	VectorStore VectorStoreConfig `json:"vectorStore,omitempty"`

	// Embedding configures how documents are chunked and embedded.
	Embedding EmbeddingConfig `json:"embedding"`

	// Ingestion defines document sources. If nil, documents are only added
	// at runtime via the _rag_ingest tool.
	// +optional
	Ingestion *IngestionConfig `json:"ingestion,omitempty"`
}

type KnowledgeBaseStatus struct {
	// Ready indicates the vector store is accessible and has been seeded.
	// +optional
	Ready bool `json:"ready,omitempty"`

	// Message contains a human-readable status message. Populated on failure
	// (e.g. "Qdrant pod failed to start: CrashLoopBackOff") or when waiting
	// (e.g. "Qdrant pod not ready yet"). Empty once the KnowledgeBase is ready.
	// +optional
	Message string `json:"message,omitempty"`

	// DocumentCount is the number of source documents ingested.
	// +optional
	DocumentCount int `json:"documentCount,omitempty"`

	// ChunkCount is the number of vector chunks stored.
	// +optional
	ChunkCount int `json:"chunkCount,omitempty"`

	// VectorStoreURL is the resolved Qdrant endpoint.
	// +optional
	VectorStoreURL string `json:"vectorStoreURL,omitempty"`

	// CollectionName is the resolved Qdrant collection name.
	// +optional
	CollectionName string `json:"collectionName,omitempty"`

	// EmbeddingModelProvider is the name of the ModelProvider CR used when the
	// Qdrant collection was first created. Once set, all subsequent embedding
	// calls use this provider directly to prevent dimension mismatches caused
	// by a ModelSelector routing to a different model between calls.
	// +optional
	EmbeddingModelProvider string `json:"embeddingModelProvider,omitempty"`

	// EmbeddingModel is the LiteLLM model string (e.g. "openai/text-embedding-3-large")
	// from the pinned ModelProvider.
	// +optional
	EmbeddingModel string `json:"embeddingModel,omitempty"`

	// EmbeddingDimensions is the vector size discovered from the embedding model on first use.
	// The controller probes the embedding API with a test string and records the actual output
	// dimension here. This prevents the user from having to specify dimensions manually and
	// eliminates Qdrant dimension-mismatch errors caused by mismatched configuration.
	// +optional
	EmbeddingDimensions int `json:"embeddingDimensions,omitempty"`

	// StorageUsedPercent is the percentage of PVC storage consumed by Qdrant (0–100).
	// +optional
	StorageUsedPercent int `json:"storageUsedPercent,omitempty"`

	// LastSyncTime is when documents were last ingested.
	// +optional
	LastSyncTime *metav1.Time `json:"lastSyncTime,omitempty"`

	// IngestionBreakers tracks the ingestion circuit breaker per source,
	// keyed by that source's ingestion Job name ("kb-src-<kb>" for static
	// sources, "kb-mcp-<kb>-<idx>" for MCP sources). Keying per source is
	// load-bearing: a sibling source's success must not cancel a failed
	// source's backoff pause (which recreated the runaway Job loop), and
	// concurrent source failures must not amplify each other's counters.
	// +optional
	IngestionBreakers map[string]IngestionBreakerState `json:"ingestionBreakers,omitempty"`

	// IngestionSyncTimes records the last successful sync per source, keyed
	// by that source's ingestion Job name. The sync-interval gate reads
	// these instead of the single KB-level LastSyncTime so a persistently
	// failing sibling source cannot starve a healthy source's configured
	// sync cadence (LastSyncTime only advances when nothing is running and
	// no source errored).
	// +optional
	IngestionSyncTimes map[string]metav1.Time `json:"ingestionSyncTimes,omitempty"`

	// QdrantVersion is the currently running Qdrant version as reported by
	// the instance's HTTP API (e.g. "1.17.1"). Empty until the first probe.
	// +optional
	QdrantVersion string `json:"qdrantVersion,omitempty"`

	// QdrantTargetVersion is the operator's desired Qdrant version for this
	// KnowledgeBase. Derived from the operator build or Helm override.
	// +optional
	QdrantTargetVersion string `json:"qdrantTargetVersion,omitempty"`

	// QdrantUpgradeState tracks in-progress sequential upgrades.
	// Empty when no upgrade is in progress.
	// +kubebuilder:validation:Enum="";Snapshot;WaitingForReady;Failed
	// +optional
	QdrantUpgradeState string `json:"qdrantUpgradeState,omitempty"`

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

type LocalObjectRef struct {
	// Name of the resource.
	Name string `json:"name"`
}

type LoopDetectedInfo struct {
	// Reason is a human-readable description of which safeguard was tripped.
	Reason string `json:"reason"`

	// TripCount is the counter value that exceeded the configured limit.
	TripCount int `json:"tripCount"`

	// ToolName is the name of the tool involved, for tool-based trips.
	// +optional
	ToolName string `json:"toolName,omitempty"`
}

type MCPAuthConfig struct {
	// BearerToken sets the Authorization header to "Bearer <token>".
	// The token value is read from a Kubernetes Secret.
	// +optional
	BearerToken *SecretKeyRef `json:"bearerToken,omitempty"`

	// APIKey sets a custom header with a key read from a Secret.
	// +optional
	APIKey *APIKeyAuth `json:"apiKey,omitempty"`

	// Headers sets custom HTTP headers from Secrets.
	// Use this for non-standard auth schemes.
	// +optional
	Headers []AuthHeader `json:"headers,omitempty"`

	// OAuth drives OAuth 2.0 token management for the remote MCP server (HTTP/SSE).
	// When set, the MCPServer controller discovers the server's OAuth config from its
	// RFC 8414 metadata, exchanges a refresh token (or a one-time authorization code
	// via PKCE) for an access token, writes it to accessTokenSecretRef, and wires
	// auth.bearerToken to that Secret so the model-router sends it as a bearer. This is
	// what makes OAuth-only MCP servers usable (e.g. Slack, which rejects static tokens
	// with -32001 invalid_token). Mutually exclusive with bearerToken/apiKey/headers.
	// +optional
	OAuth *MCPOAuthConfig `json:"oauth,omitempty"`
}

type MCPConfig struct {
	// Transport is the MCP transport protocol.
	// +kubebuilder:validation:Enum=stdio;http;sse
	// +kubebuilder:default=stdio
	// +optional
	Transport string `json:"transport,omitempty"`

	// URL is the MCP server URL for http and sse transports.
	// If set, the server runs externally and no sidecar is injected.
	// +optional
	URL string `json:"url,omitempty"`

	// Args are the command-line arguments passed to the MCP server process.
	// Only used for stdio transport.
	// +optional
	Args []string `json:"args,omitempty"`

	// Env sets environment variables for the MCP server process.
	// +optional
	Env map[string]string `json:"env,omitempty"`

	// EnvFrom sets environment variables sourced from Kubernetes Secrets.
	// These are merged with (and override) Env entries of the same name.
	// +optional
	EnvFrom []EnvVar `json:"envFrom,omitempty"`

	// Auth configures authentication for HTTP/SSE transports.
	// Not supported for stdio transport (use EnvFrom instead).
	// +optional
	Auth *MCPAuthConfig `json:"auth,omitempty"`
}

type MCPIngestionSource struct {
	// MCPServerRef names the MCPServer CR (same namespace) to use.
	// The MCPServer must include "_controller" in its allowedAgents list.
	// +kubebuilder:validation:MinLength=1
	MCPServerRef string `json:"mcpServerRef"`

	// Discover is an optional tool call that returns a list of items to iterate.
	// If omitted, Fetch runs once with its static arguments.
	// +optional
	Discover *MCPToolCall `json:"discover,omitempty"`

	// ItemExtractor configures how to extract individual items from the
	// discover result:
	//   - "lines": split by newline, skip empty lines (default).
	//   - "jsonArray": parse as a JSON array of strings.
	//   - "jsonObjects": parse as a JSON array of objects; requires ItemField.
	// +kubebuilder:validation:Enum=lines;jsonArray;jsonObjects
	// +kubebuilder:default=lines
	// +optional
	ItemExtractor string `json:"itemExtractor,omitempty"`

	// ItemField selects which field to extract from each JSON object when
	// ItemExtractor is "jsonObjects". For example, "path" extracts the
	// "path" key from each object. Required when ItemExtractor is "jsonObjects".
	// +optional
	ItemField string `json:"itemField,omitempty"`

	// ItemFilter optionally filters JSON objects before extraction (only
	// applies to "jsonObjects"). Objects are included only when the named
	// field equals the specified value. For example, setting key="type" and
	// value="file" keeps only objects where type is "file".
	// +optional
	ItemFilter *ItemFilterConfig `json:"itemFilter,omitempty"`

	// DiscoverRecursive enables recursive directory traversal. When true,
	// items matching DirectoryFilter are re-discovered by calling the
	// Discover tool with "{{item}}" in its arguments replaced by the
	// directory path. Requires Discover.Arguments to contain "{{item}}".
	// +optional
	DiscoverRecursive bool `json:"discoverRecursive,omitempty"`

	// DirectoryFilter identifies directory entries in discover results.
	// Required when DiscoverRecursive is true. Objects matching this
	// filter are queued for recursive discovery rather than fetched.
	// +optional
	DirectoryFilter *ItemFilterConfig `json:"directoryFilter,omitempty"`

	// IncludePatterns is a list of glob patterns. If non-empty, only
	// items matching at least one pattern are kept. Supports "**" for
	// recursive matching (e.g. "**/*.go", "docs/**").
	// +optional
	IncludePatterns []string `json:"includePatterns,omitempty"`

	// ExcludePatterns is a list of glob patterns. Items matching any
	// pattern are dropped (applied after IncludePatterns).
	// Supports "**" for recursive matching (e.g. "vendor/**").
	// +optional
	ExcludePatterns []string `json:"excludePatterns,omitempty"`

	// Fetch is the tool call to execute for each discovered item (or once
	// if no Discover step). String values in Arguments may contain
	// "{{item}}" which is replaced with each discovered item.
	Fetch MCPToolCall `json:"fetch"`

	// MaxItems caps the number of items processed from the discover step.
	// Prevents runaway ingestion. 0 means unlimited.
	// +kubebuilder:default=500
	// +optional
	MaxItems int `json:"maxItems,omitempty"`

	// DocumentIDTemplate is a Go template for generating document IDs.
	// Available variables: {{.Item}}, {{.MCPServer}}, {{.Tool}}.
	// Defaults to "mcp/{{.MCPServer}}/{{.Item}}".
	// +optional
	DocumentIDTemplate string `json:"documentIDTemplate,omitempty"`

	// Resources sets CPU/memory for the ingestion Job pod.
	// +optional
	Resources *ResourceRequirements `json:"resources,omitempty"`
}

type MCPOAuthConfig struct {
	// Credentials is a Secret (in the MCPServer's namespace) holding the OAuth client
	// id/secret (keys: client_id, client_secret), an optional registered redirect_uri
	// (key: redirect_uri), and an optional pre-provisioned refresh_token (key:
	// refresh_token). Supplying a refresh_token skips the one-time authorization-code
	// seed; otherwise the controller reports "seeding required" and the operator runs
	// `oauth-proxy seed` once.
	// +required
	Credentials LocalObjectRef `json:"credentials"`
	// Scopes overrides the server's scopes_supported; if empty, discovery scopes win.
	// +optional
	Scopes []string `json:"scopes,omitempty"`
	// RefreshTokenSecretRef optionally points to a Secret/key holding just the refresh
	// token (instead of inside Credentials). When set, this takes precedence.
	// +optional
	RefreshTokenSecretRef *SecretKeyRef `json:"refreshTokenSecretRef,omitempty"`
	// AccessTokenSecretRef is the Secret (key "token") the access token is written to
	// and that auth.bearerToken references. If omitted, the controller names it
	// "<mcpserver>-mcp-token" (key "token").
	// +optional
	AccessTokenSecretRef *SecretKeyRef `json:"accessTokenSecretRef,omitempty"`
}

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

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

	Spec   MCPServerSpec   `json:"spec,omitempty"`
	Status MCPServerStatus `json:"status,omitempty"`
}

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

type MCPServerSpec struct {
	// Transport is the MCP transport protocol.
	// +kubebuilder:validation:Enum=stdio;http;sse
	// +kubebuilder:default=stdio
	// +optional
	Transport string `json:"transport,omitempty"`

	// URL is the MCP server URL for http and sse transports.
	// If set, the server runs externally and no sidecar is injected.
	// +optional
	URL string `json:"url,omitempty"`

	// OCIRef is the OCI image reference for stdio transport servers
	// that run as a sidecar. Must be signed with Cosign unless
	// imageVerification.skip is true.
	// +optional
	OCIRef string `json:"ociRef,omitempty"`

	// Args are the command-line arguments passed to the MCP server process.
	// Only used for stdio transport.
	// +optional
	Args []string `json:"args,omitempty"`

	// Env sets environment variables for the MCP server process.
	// +optional
	Env map[string]string `json:"env,omitempty"`

	// EnvFrom sets environment variables sourced from Kubernetes Secrets.
	// These are merged with (and override) Env entries of the same name.
	// Only used for stdio transport.
	// +optional
	EnvFrom []EnvVar `json:"envFrom,omitempty"`

	// Auth configures authentication for HTTP/SSE transports.
	// The model-router reads each referenced Secret (mounted as a file into the
	// sidecar) and injects it as an HTTP header on every request to the remote
	// MCP server. Not supported for stdio transport (use EnvFrom instead — the
	// agentorca admission webhook rejects auth on stdio).
	// +optional
	Auth *MCPAuthConfig `json:"auth,omitempty"`

	// Tools declares the tools this MCP server provides.
	// Each entry becomes a child Tool CR managed by the MCPServer controller.
	//
	// Optional when spec.discoverability is "enabled" (the default): if Tools is
	// empty the controller creates a single connector Tool CR (named after the
	// MCPServer) and the model-router discovers every tool at runtime via tools/list.
	// When spec.discoverability is "disabled", Tools is required.
	// +optional
	Tools []MCPServerTool `json:"tools,omitempty"`

	// Discoverability controls how MCP tools are surfaced to agents.
	//
	// "enabled" (default): the model-router auto-discovers all tools at runtime via
	// tools/list and exposes them to the LLM. spec.tools is optional — when omitted,
	// the controller creates one connector Tool CR (named after the MCPServer) and the
	// agent references the server by that name. Any tools declared in spec.tools are
	// still created as child Tool CRs (useful for access-control cataloguing).
	//
	// "disabled": spec.tools is required and the agent must reference each declared
	// Tool CR explicitly.
	// +kubebuilder:validation:Enum=enabled;disabled
	// +kubebuilder:default=enabled
	// +optional
	Discoverability string `json:"discoverability,omitempty"`

	// IncludePatterns is a list of glob patterns used to filter the tools the
	// model-router discovers at runtime. When non-empty, only tools whose name matches
	// at least one pattern are exposed to agents. Supports "*", "?", and "**" for
	// recursive multi-segment matching (e.g. "search/**"). Mirrors the
	// includePatterns convention used by KnowledgeBase ingestion.
	// +optional
	IncludePatterns []string `json:"includePatterns,omitempty"`

	// ExcludePatterns is a list of glob patterns to hide discovered tools. A tool
	// matching any pattern is dropped before it reaches the LLM, even if it matched
	// an IncludePatterns entry (exclude always wins). Applied after IncludePatterns.
	// +optional
	ExcludePatterns []string `json:"excludePatterns,omitempty"`

	// AllowedAgents is the explicit list of Agent names (in the same namespace) that are
	// permitted to use this MCP server. Access is denied by default — if this list is
	// empty, no agent may access the server regardless of what tools it declares.
	//
	// The agent-orca operator enforces this at AgentRun creation time: if the agent
	// running the run is not listed here, the run is failed before the pod is scheduled.
	// At runtime, the model-router sidecar sends a short-lived Kubernetes ServiceAccount
	// JWT (audience "agentorca/mcp") with every HTTP/SSE request to the MCP server so the
	// server can independently verify the caller's identity via the TokenReview API.
	//
	// Example — grant access to two agents:
	//   allowedAgents:
	//   - analyst
	//   - report-builder
	// +optional
	AllowedAgents []string `json:"allowedAgents,omitempty"`

	// NetworkEgress defines additional outbound network rules for agent pods
	// using tools from this MCP server.
	// +optional
	NetworkEgress []EgressRule `json:"networkEgress,omitempty"`

	// Resources sets CPU/memory limits for the MCP server sidecar.
	// +optional
	Resources *ResourceRequirements `json:"resources,omitempty"`

	// AllowApps enables MCP App rendering for this server. When false (default),
	// _meta.ui.resourceUri is ignored and no sandboxed iframe is rendered in the UI.
	// Set to true only for MCP servers whose HTML output you explicitly trust.
	// +optional
	AllowApps bool `json:"allowApps,omitempty"`
}

type MCPServerStatus struct {
	// Ready indicates all child Tools were created successfully.
	// +optional
	Ready bool `json:"ready,omitempty"`

	// Discovering is true when spec.discoverability is "enabled" and spec.tools is
	// empty, meaning the controller created a connector Tool CR and the model-router
	// will discover all tools at runtime via tools/list.
	// +optional
	Discovering bool `json:"discovering,omitempty"`

	// Message contains a human-readable status message.
	// +optional
	Message string `json:"message,omitempty"`

	// ToolCount is the number of child Tool CRs managed by this MCPServer.
	// +optional
	ToolCount int `json:"toolCount,omitempty"`

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

type MCPServerTool struct {
	// Name is the tool name. Combined with the MCPServer name to form the
	// child Tool CR name: <mcpserver>-<name>.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:Pattern=`^[a-z0-9]([a-z0-9-]*[a-z0-9])?$`
	Name string `json:"name"`

	// Description is a human-readable description shown to the LLM.
	// +optional
	Description string `json:"description,omitempty"`

	// InputSchema is a JSON Schema object for the tool's input parameters.
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	InputSchema *runtime.RawExtension `json:"inputSchema,omitempty"`
}

type MCPToolCall struct {
	// Tool is the MCP tool name to call (e.g. "get_file_contents").
	// +kubebuilder:validation:MinLength=1
	Tool string `json:"tool"`

	// Arguments is a JSON object of tool arguments.
	// String values may contain "{{item}}" placeholders when used in
	// the Fetch step of an MCPIngestionSource.
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	Arguments *runtime.RawExtension `json:"arguments,omitempty"`
}

type MetaRouterConfig struct {
	// ProviderRef is the name of a ModelProvider to use for routing decisions.
	// Should be a cheap, fast model (e.g., a small local model or a flash variant).
	ProviderRef string `json:"providerRef"`

	// Threshold is the minimum rule-router confidence score below which the
	// meta-router is invoked. Range 0.0–1.0. Defaults to 0.6.
	// +kubebuilder:validation:Pattern=`^(0(\.\d+)?|1(\.0+)?)$`
	// +kubebuilder:default="0.6"
	// +optional
	Threshold string `json:"threshold,omitempty"`
}

type ModelConstraints struct {
	// ContextWindow is the maximum number of tokens the model accepts.
	// +optional
	ContextWindow int `json:"contextWindow,omitempty"`

	// MaxOutputTokens is the maximum number of tokens the model can generate.
	// +optional
	MaxOutputTokens int `json:"maxOutputTokens,omitempty"`

	// MaxRequestTokens is the effective per-request token limit for this provider.
	// When set, the router will not route requests whose estimated token count
	// exceeds this value to this provider. Use this when the provider's account-level
	// rate limit (e.g. TPM) is lower than the model's ContextWindow.
	// 0 means no per-request limit (ContextWindow is used for sizing decisions).
	// +optional
	MaxRequestTokens int `json:"maxRequestTokens,omitempty"`

	// CostPerMillionInputTokens is the USD cost per million input tokens as a decimal string.
	// Example: "3.00" (i.e. $3 per million input tokens)
	// +optional
	CostPerMillionInputTokens string `json:"costPerMillionInputTokens,omitempty"`

	// CostPerMillionOutputTokens is the USD cost per million output tokens as a decimal string.
	// Example: "15.00" (i.e. $15 per million output tokens)
	// +optional
	CostPerMillionOutputTokens string `json:"costPerMillionOutputTokens,omitempty"`

	// RPM is the account-level requests-per-minute budget for this provider's
	// API key. Embedding calls are paced to stay under it. When unset, the
	// operator applies built-in conservative presets keyed by the provider
	// endpoint (e.g. Google AI Studio free tier, OpenAI tier 1).
	// +optional
	RPM int `json:"rpm,omitempty"`

	// TPM is the account-level tokens-per-minute budget for this provider's
	// API key. Embedding batches are sized and paced to stay under it. When
	// unset, the operator applies built-in conservative presets keyed by the
	// provider endpoint.
	// +optional
	TPM int `json:"tpm,omitempty"`
}

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

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

	Spec   ModelProviderSpec   `json:"spec,omitempty"`
	Status ModelProviderStatus `json:"status,omitempty"`
}

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

type ModelProviderSpec struct {
	// LiteLLMModel is the LiteLLM model identifier used to dispatch requests.
	// Examples:
	//   "anthropic/claude-sonnet-4-6"
	//   "gemini/gemini-2.0-flash"
	//   "ollama/llama3.2"
	//   "bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0"
	//   "openai/gpt-4o"
	// +kubebuilder:validation:MinLength=1
	LiteLLMModel string `json:"litellmModel"`

	// BaseURL overrides the default API endpoint derived from the LiteLLM model prefix.
	// Use this for self-hosted models (e.g. "http://ollama.default.svc:11434")
	// or when the provider endpoint differs from the default.
	// +optional
	BaseURL string `json:"baseURL,omitempty"`

	// CredentialsRef points to the Secret containing the provider API key.
	// The model-router sidecar mounts this secret directly; the operator never reads it.
	CredentialsRef SecretKeyRef `json:"credentialsRef"`

	// Capabilities tags this model's strengths, used by the rule-based router.
	// Known values: reasoning, code, vision, fast, long-context, cheap
	// +optional
	Capabilities []string `json:"capabilities,omitempty"`

	// Constraints describes the model's resource limits and pricing.
	// +optional
	Constraints ModelConstraints `json:"constraints,omitempty"`

	// LatencyProfile is a coarse latency classification used by the router.
	// +kubebuilder:validation:Enum=fast;medium;slow
	// +kubebuilder:default=medium
	// +optional
	LatencyProfile string `json:"latencyProfile,omitempty"`

	// QueryPrompt is an optional prefix prepended to query text before embedding.
	// Required by some open-source embedding models (e.g. nomic-embed-text via
	// Ollama) that need task-specific instructions to produce retrieval-quality
	// vectors. When set, this prefix is applied to _rag_search query embeddings.
	// Example: "search_query: "
	// +optional
	QueryPrompt string `json:"queryPrompt,omitempty"`

	// DocPrompt is an optional prefix prepended to document chunks before embedding.
	// Required by some open-source embedding models (e.g. nomic-embed-text via
	// Ollama) that need task-specific instructions to produce retrieval-quality
	// vectors. When set, this prefix is applied to _rag_ingest document embeddings.
	// Example: "search_document: "
	// +optional
	DocPrompt string `json:"docPrompt,omitempty"`
}

type ModelProviderStatus struct {
	// Ready indicates the provider endpoint is reachable and credentials are valid.
	// +optional
	Ready bool `json:"ready,omitempty"`

	// Message contains a human-readable status message.
	// +optional
	Message string `json:"message,omitempty"`

	// LastChecked is the last time the provider was health-checked.
	// +optional
	LastChecked *metav1.Time `json:"lastChecked,omitempty"`

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

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

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

	Spec   ModelSelectorSpec   `json:"spec,omitempty"`
	Status ModelSelectorStatus `json:"status,omitempty"`
}

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

type ModelSelectorSpec struct {
	// Strategy determines how the model-router selects a provider for each request.
	// - rule-based: deterministic routing via capability tags, cost, and latency SLOs
	// - llm-meta:   a cheap LLM decides which model to use for each request
	// - hybrid:     rule-based fast path with LLM meta-router for low-confidence cases
	// +kubebuilder:validation:Enum=rule-based;llm-meta;hybrid
	// +kubebuilder:default=rule-based
	// +optional
	Strategy string `json:"strategy,omitempty"`

	// Providers lists the ModelProviders available to this selector and their weights.
	// Weights are used for weighted random selection when no other routing rule applies.
	// +kubebuilder:validation:MinItems=1
	Providers []ProviderWeight `json:"providers"`

	// FallbackChain is an ordered list of ModelProvider names used when a provider
	// returns a 429 or 5xx. The router tries each in order.
	// +optional
	FallbackChain []string `json:"fallbackChain,omitempty"`

	// BudgetCap enforces spending limits per run and per day.
	// +optional
	BudgetCap *BudgetCap `json:"budgetCap,omitempty"`

	// CapabilityRouting maps capability tags to preferred provider names.
	// Example: {"code": "gpt-4o", "reasoning": "claude-sonnet", "fast": "llama3-local"}
	// +optional
	CapabilityRouting map[string]string `json:"capabilityRouting,omitempty"`

	// MetaRouter configures the LLM meta-router used in "llm-meta" and "hybrid" strategies.
	// +optional
	MetaRouter *MetaRouterConfig `json:"metaRouter,omitempty"`
}

type ModelSelectorStatus struct {
	// ActiveProviders lists ModelProvider names that are currently healthy.
	// +optional
	ActiveProviders []string `json:"activeProviders,omitempty"`

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

type NetworkIsolationSpec struct {
	// SplitPod runs the agent and model-router in separate Pods with distinct NetworkPolicies.
	// The agent pod's egress is restricted to the router Service (ports 8080/8082) and DNS.
	// The router pod retains all required egress (provider HTTPS, Kubernetes API, Redis, tools).
	// This provides a Kubernetes-level network guarantee that agent code cannot open arbitrary
	// outbound connections when platform policy requires all LLM traffic to go via model-router.
	// +kubebuilder:default=false
	// +optional
	SplitPod bool `json:"splitPod,omitempty"`
}

type PodSecurityOverride struct {
	// Privileged grants the agent container full privileges (CAP_NET_ADMIN,
	// /dev/net/tun device access, seccomp/capability enforcement disabled). Use this
	// for tun-device VPNs. Mutually exclusive with AddCapabilities.
	// +optional
	Privileged bool `json:"privileged,omitempty"`

	// AddCapabilities adds specific capabilities to the agent container while keeping
	// the restricted profile otherwise (e.g. ["NET_ADMIN"] + a /dev/net/tun hostPath
	// mount). Mutually exclusive with Privileged.
	// +optional
	AddCapabilities []string `json:"addCapabilities,omitempty"`

	// RunAsUser overrides the default non-root UID (65532). 0 (root) is permitted only
	// when Privileged is true or a capability that requires root (e.g. NET_ADMIN to
	// create network interfaces) is added; the webhook enforces this.
	// +optional
	RunAsUser *int64 `json:"runAsUser,omitempty"`

	// ReadOnlyRootFilesystem overrides the default read-only root filesystem of the
	// agent container. When omitted and Privileged is true, defaults to writable
	// (false) since some security tooling writes helpers/logs to the root FS; when
	// omitted and non-privileged, retains the restricted default (true).
	// +optional
	ReadOnlyRootFilesystem *bool `json:"readOnlyRootFilesystem,omitempty"`
}

type ProviderWeight struct {
	// Name is the name of a ModelProvider in the same namespace.
	Name string `json:"name"`

	// Weight controls the probability of selecting this provider when using weighted
	// random selection. Higher values mean more traffic. Defaults to 100.
	// Set to 0 to exclude from random selection (meta-router and error fallback only).
	// +kubebuilder:default=100
	// +optional
	Weight int `json:"weight,omitempty"`

	// RoutingHint is a short description passed to the LLM meta-router to help it
	// decide when to select this provider. Example:
	//   "Use for complex, security-sensitive changes: auth, crypto, architecture."
	// +optional
	RoutingHint string `json:"routingHint,omitempty"`
}

type RegexPattern struct {
	// Name identifies this pattern (e.g. "ssn", "email", "credit-card").
	Name string `json:"name"`

	// Pattern is a Go-compatible regular expression.
	// +kubebuilder:validation:MinLength=1
	Pattern string `json:"pattern"`

	// Replacement is the string that replaces matched content when action is "redact".
	// +optional
	Replacement string `json:"replacement,omitempty"`
}

type ResourceRequirements = corev1.ResourceRequirements

type RoutingDecision struct {
	// Model is the selected model identifier (e.g. "anthropic/claude-sonnet-4-6").
	Model string `json:"model"`

	// Provider is the ModelProvider CRD name that was selected.
	Provider string `json:"provider"`

	// Strategy is the routing strategy used (e.g. "rule-based", "llm-meta", "hybrid").
	Strategy string `json:"strategy,omitempty"`

	// Reason is a human-readable explanation of why this provider was chosen.
	Reason string `json:"reason,omitempty"`

	// Confidence is a 0.0–1.0 score indicating routing confidence.
	// +optional
	Confidence string `json:"confidence,omitempty"`

	// Timestamp is when the routing decision was made.
	// +optional
	Timestamp *metav1.Time `json:"timestamp,omitempty"`
}

type S3IngestionSource struct {
	// Bucket is the S3 bucket name.
	Bucket string `json:"bucket"`

	// Prefix filters objects by key prefix.
	// +optional
	Prefix string `json:"prefix,omitempty"`

	// Region is the AWS region (or S3-compatible endpoint region).
	// +optional
	Region string `json:"region,omitempty"`

	// Endpoint is the S3-compatible API endpoint (e.g. "http://minio.default.svc:9000"
	// for MinIO). Empty means AWS S3.
	// +optional
	Endpoint string `json:"endpoint,omitempty"`

	// SecretRef references a Secret containing AWS credentials.
	// Expected keys: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY.
	// +optional
	SecretRef *SecretKeyRef `json:"secretRef,omitempty"`
}

type SecretKeyRef struct {
	// Name of the Secret.
	Name string `json:"name"`
	// Key within the Secret.
	Key string `json:"key"`
	// Namespace of the Secret. Defaults to the same namespace as the referencing resource.
	// +optional
	Namespace string `json:"namespace,omitempty"`
}

type SecretMount struct {
	// Name of the Secret in the same namespace.
	Name string `json:"name"`
	// MountPath is the filesystem path where the Secret should be mounted.
	// If empty, the Secret's keys are injected as environment variables instead.
	// +optional
	MountPath string `json:"mountPath,omitempty"`
}

type StepProposal struct {
	// ProposingStep is the name of the workflow step whose agent made the proposal.
	ProposingStep string `json:"proposingStep"`

	// ProposedStep is the step definition that was proposed.
	ProposedStep WorkflowStep `json:"proposedStep"`

	// Approved indicates whether the proposal was accepted.
	Approved bool `json:"approved"`

	// Reason explains why the proposal was approved or rejected.
	// +optional
	Reason string `json:"reason,omitempty"`

	// Timestamp is when the proposal was evaluated.
	Timestamp metav1.Time `json:"timestamp"`

	// PendingHumanApproval is true when the proposal requires human review.
	// The proposing step is paused (WaitingForInput) until a human responds.
	// +optional
	PendingHumanApproval bool `json:"pendingHumanApproval,omitempty"`
}

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

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

	Spec   TenantConfigSpec   `json:"spec,omitempty"`
	Status TenantConfigStatus `json:"status,omitempty"`
}

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

type TenantConfigSpec struct {
	// AuthMode selects the authentication strategy for this tenant.
	// "issued" — agent-orca issues OAuth2 tokens via client_credentials grant.
	// "federated" — agent-orca trusts JWTs from the tenant's external IdP.
	// +kubebuilder:validation:Enum=issued;federated
	AuthMode string `json:"authMode"`

	// Issued configures agent-orca-issued OAuth2 client credentials.
	// Required when AuthMode is "issued".
	// +optional
	Issued *IssuedAuthConfig `json:"issued,omitempty"`

	// Federated configures trust for an external OIDC identity provider.
	// Required when AuthMode is "federated".
	// +optional
	Federated *FederatedAuthConfig `json:"federated,omitempty"`

	// AllowedNamespaces is the set of Kubernetes namespaces whose agents and
	// resources this tenant is authorized to access. The operator resolves each
	// agent to the namespace it actually lives in — which must be one of these —
	// when a task is submitted or an ACP run is created, so a single tenant can
	// span multiple namespaces. List operations (agents, runs) span the whole set;
	// per-request writes are directed to the agent's namespace.
	// +kubebuilder:validation:MinItems=1
	AllowedNamespaces []string `json:"allowedNamespaces"`

	// AllowedAgents restricts which agents this tenant may invoke.
	// An empty list means no agents are allowed; omitting the field allows all agents
	// in the allowed namespaces.
	// +optional
	AllowedAgents []string `json:"allowedAgents,omitempty"`

	// RateLimit configures request rate limiting for this tenant.
	// +optional
	RateLimit *TenantRateLimit `json:"rateLimit,omitempty"`

	// BudgetPerDayUSD is the maximum daily spend in USD for this tenant.
	// Enforced across all runs in the allowed namespaces attributed to this tenant.
	// +optional
	BudgetPerDayUSD string `json:"budgetPerDayUSD,omitempty"`
}

type TenantConfigStatus struct {
	// Ready indicates the tenant configuration has been validated and is active.
	// +optional
	Ready bool `json:"ready,omitempty"`

	// Message contains a human-readable status message.
	// +optional
	Message string `json:"message,omitempty"`

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

type TenantRateLimit struct {
	// RequestsPerMinute is the maximum number of task submissions per minute.
	// +optional
	RequestsPerMinute int `json:"requestsPerMinute,omitempty"`

	// ConcurrentRuns is the maximum number of simultaneously running AgentRuns.
	// +optional
	ConcurrentRuns int `json:"concurrentRuns,omitempty"`
}

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

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

	Spec   ToolSpec   `json:"spec,omitempty"`
	Status ToolStatus `json:"status,omitempty"`
}

type ToolExecutionMode string

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

type ToolSchema struct {
	// Description is a human-readable description shown to the LLM.
	// +optional
	Description string `json:"description,omitempty"`

	// Input is a JSON Schema object for the tool's input parameters.
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	Input *runtime.RawExtension `json:"input,omitempty"`

	// Output is a JSON Schema object for the tool's output.
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	Output *runtime.RawExtension `json:"output,omitempty"`
}

type ToolSpec struct {
	// Type declares the tool implementation kind.
	// +kubebuilder:default=regular
	// +optional
	Type ToolType `json:"type,omitempty"`

	// OCIRef is the OCI image reference for regular, agent-type (ignored), and wasm tools.
	// Must be signed with Cosign unless imageVerification.skip is true.
	// Not required for mcp tools that use a static URL.
	// +optional
	OCIRef string `json:"ociRef,omitempty"`

	// AgentRef names the Agent CRD to expose as a tool.
	// Only used when Type is "agent".
	// +optional
	AgentRef string `json:"agentRef,omitempty"`

	// ExecutionMode controls how the tool runs.
	// Defaults to "pod" for regular tools, "sidecar" for mcp tools, "wasm" for wasm tools.
	// +optional
	ExecutionMode ToolExecutionMode `json:"executionMode,omitempty"`

	// Schema is the JSON Schema for the tool's input and output.
	// Exposed to agents as an OpenAI function definition.
	// +optional
	Schema *ToolSchema `json:"schema,omitempty"`

	// MCPConfig configures an MCP server. Only used when Type is "mcp".
	// +optional
	MCPConfig *MCPConfig `json:"mcpConfig,omitempty"`

	// NetworkEgress defines additional outbound network rules for tool pods.
	// Added to the per-run NetworkPolicy allowlist.
	// +optional
	NetworkEgress []EgressRule `json:"networkEgress,omitempty"`

	// Resources sets CPU/memory limits for the tool pod or sidecar.
	// +optional
	Resources *ResourceRequirements `json:"resources,omitempty"`

	// SecretRefs lists Kubernetes Secrets to inject into tool pods or MCP sidecars.
	// For pod-type tools: mounted as volumes or env vars in the tool pod.
	// For MCP sidecar tools: mounted into the model-router sidecar container.
	// +optional
	SecretRefs []SecretMount `json:"secretRefs,omitempty"`

	// CloudAuth configures cloud-provider identity for tool pods.
	// Overrides Agent-level cloudAuth for this tool.
	// +optional
	CloudAuth *CloudAuthSpec `json:"cloudAuth,omitempty"`

	// Command overrides the container entrypoint for pod-type tools.
	// +optional
	Command []string `json:"command,omitempty"`

	// Args overrides the container command arguments for pod-type tools.
	// +optional
	Args []string `json:"args,omitempty"`
}

type ToolStatus struct {
	// Ready indicates the tool is validated and available.
	// +optional
	Ready bool `json:"ready,omitempty"`

	// Message contains a human-readable status message.
	// +optional
	Message string `json:"message,omitempty"`

	// SignatureVerified indicates the OCI artifact signature was verified by Cosign.
	// +optional
	SignatureVerified bool `json:"signatureVerified,omitempty"`

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

type ToolType string

type VectorStoreConfig struct {
	// Provider is the vector store implementation: "qdrant" (default).
	// +kubebuilder:validation:Enum=qdrant
	// +kubebuilder:default=qdrant
	// +optional
	Provider string `json:"provider,omitempty"`

	// CollectionName overrides the Qdrant collection name.
	// Defaults to the KnowledgeBase CR name.
	// +optional
	CollectionName string `json:"collectionName,omitempty"`

	// StorageSize is the PVC size for the Qdrant StatefulSet.
	// +kubebuilder:default="10Gi"
	// +optional
	StorageSize string `json:"storageSize,omitempty"`

	// Resources overrides default CPU/memory for the Qdrant pod.
	// +optional
	Resources *ResourceRequirements `json:"resources,omitempty"`

	// AutoUpgrade controls whether the operator automatically upgrades the
	// Qdrant instance to match the operator's target version. When true
	// (default), the operator walks through sequential minor versions with
	// a snapshot before each step. Set to false to hold the current version.
	// +kubebuilder:default=true
	// +optional
	AutoUpgrade *bool `json:"autoUpgrade,omitempty"`
}

type WebhookNotifyConfig struct {
	// WebhookSecretRef references a Secret whose key (default "url") holds the Slack
	// incoming-webhook URL. The Secret is mounted into the model-router sidecar as the
	// WEBHOOK_URL environment variable (not into the agent container).
	// +optional
	WebhookSecretRef *corev1.SecretKeySelector `json:"webhookSecretRef,omitempty"`
}

type WorkflowBudgetCap struct {
	// Total is the maximum USD spend across all AgentRuns in the workflow.
	// When exceeded, the currently-running step is failed and the workflow is Failed.
	Total string `json:"total"`
}

type WorkflowStep struct {
	// Name is a unique identifier for this step within the workflow.
	// Used in DependsOn references and template variables.
	// +kubebuilder:validation:Pattern=`^[a-z0-9][a-z0-9\-]*$`
	Name string `json:"name"`

	// AgentRef is the name of the Agent CRD to run for this step.
	AgentRef string `json:"agentRef"`

	// Input is the task string passed to the agent as AGENTORC_INPUT.
	// Supports template variables:
	//   {{steps.<name>.output}}  — the Output of a named predecessor step
	Input string `json:"input"`

	// DependsOn lists step names that must reach a terminal phase (Succeeded or Skipped)
	// before this step is eligible to start.
	// +optional
	DependsOn []string `json:"dependsOn,omitempty"`

	// Condition is a CEL expression evaluated before this step starts.
	// The expression has access to a "steps" variable: map of step name →
	// {phase: string, output: string}. If the expression evaluates to false
	// the step is marked Skipped rather than started.
	// Example: 'steps["gather"].phase == "Succeeded"'
	// +optional
	Condition string `json:"condition,omitempty"`

	// Timeout overrides the workflow-level timeout for this specific step.
	// +optional
	Timeout *metav1.Duration `json:"timeout,omitempty"`

	// Callbacks fires webhooks when this step completes or fails.
	// +optional
	Callbacks *CallbackConfig `json:"callbacks,omitempty"`
}

type WorkflowStepPhase string

type WorkflowStepStatus struct {
	// Name matches a step name in spec.steps.
	Name string `json:"name"`

	// Phase is the current lifecycle state of this step.
	Phase WorkflowStepPhase `json:"phase"`

	// AgentRunRef is the name of the AgentRun created for this step.
	// +optional
	AgentRunRef string `json:"agentRunRef,omitempty"`

	// StartTime is when the step's AgentRun was created.
	// +optional
	StartTime *metav1.Time `json:"startTime,omitempty"`

	// CompletionTime is when the step reached a terminal phase.
	// +optional
	CompletionTime *metav1.Time `json:"completionTime,omitempty"`

	// Output is the AgentRun output for this step, truncated to 10 KB.
	// Available to downstream steps via {{steps.<name>.output}}.
	// +optional
	Output string `json:"output,omitempty"`

	// SpendUSD is the USD spend recorded on the step's AgentRun.
	// +optional
	SpendUSD string `json:"spendUSD,omitempty"`

	// FailureReason is a human-readable explanation when Phase is Failed.
	// +optional
	FailureReason string `json:"failureReason,omitempty"`

	// Source indicates whether this step was defined statically in spec.steps
	// or added dynamically via a _propose_step call. Values: "static", "dynamic".
	// +kubebuilder:validation:Enum=static;dynamic
	// +optional
	Source string `json:"source,omitempty"`
}