controller

type AgentDeploymentReconciler struct {
	client.Client
	Scheme           *runtime.Scheme
	Recorder         record.EventRecorder
	K8s              kubernetes.Interface
	ModelRouterImage string
	// StateConfig is injected into router configs. The operator strips the Redis
	// password from it; RedisPassword carries it to a mounted Secret instead.
	StateConfig   state.Config
	RedisPassword string
	CloudProvider security.CloudProvider
	// TokenReviewerClusterRole is the ClusterRole that grants "create tokenreviews".
	TokenReviewerClusterRole string
	// OperatorAPIURL is the base URL of the operator's internal API server.
	// Injected into the router config so the model-router can call RAG, handoff, etc.
	OperatorAPIURL string
	// LLMRequestTimeout is the per-LLM-request timeout written into every router
	// config (default 1h). Injected from the LLM_REQUEST_TIMEOUT env var.
	LLMRequestTimeout time.Duration
	// ContextCompactionThreshold is the fraction of a provider's window at
	// which the router compacts the conversation (default 0.8, #47). Injected
	// from the CONTEXT_COMPACTION_THRESHOLD env var.
	ContextCompactionThreshold float64
	// ContextCompactionMode is "summary" (default) or "truncate", the rollback
	// switch (#47). Injected from the CONTEXT_COMPACTION_MODE env var.
	ContextCompactionMode string
	// ContextCompactionRatio is the fraction of the window drop-oldest
	// truncation cuts down to ("truncate" mode and the summary fallback).
	// Injected from the deprecated CONTEXT_COMPACTION_RATIO env var.
	ContextCompactionRatio float64

	// HindsightURL is the configured hindsight API endpoint (e.g. http://hindsight.local).
	// Injected from the HINDSIGHT_URL env var. Used to generate ipBlock egress rules
	// in the per-run NetworkPolicies when the cluster has a default-deny egress policy.
	HindsightURL string
	// HindsightAPIKey authenticates the model-router to a hindsight API that
	// requires a tenant API key. Injected from the HINDSIGHT_API_KEY env var; the
	// operator mirrors it into each run namespace (see ensureHindsightKeySecret).
	HindsightAPIKey string
}

type AgentReconciler struct {
	client.Client
	Scheme        *runtime.Scheme
	CloudProvider security.CloudProvider
}

type AgentRunReconciler struct {
	client.Client
	Scheme           *runtime.Scheme
	Recorder         record.EventRecorder
	K8s              kubernetes.Interface
	Dynamic          dynamic.Interface
	ModelRouterImage string
	// StateConfig is injected into router configs. The operator strips the Redis
	// password from it; RedisPassword carries it to a mounted Secret instead.
	StateConfig   state.Config
	RedisPassword string
	StateStore    state.Store
	CloudProvider security.CloudProvider
	// PostgresStore is the optional PostgreSQL archival store. When non-nil,
	// terminal-phase AgentRuns are snapshotted here for long-term retention
	// and historical querying by the UI.
	PostgresStore *postgresql.Store
	// TokenReviewerClusterRole is the name of the ClusterRole that grants
	// "create tokenreviews" — injected at startup from the Helm release name.
	// The agentrun controller binds each agent SA to this role so the
	// model-router sidecar can call the TokenReview API.
	TokenReviewerClusterRole string
	// OperatorAPIURL is the base URL of the operator's internal API server,
	// injected from the OPERATOR_API_URL env var. Written into every router
	// ConfigMap so sidecars can call /agentrun endpoints for handoff and child runs.
	// Example: "http://agent-orca-internal-api.agent-orca-system.svc.cluster.local:8082"
	OperatorAPIURL string
	// LLMRequestTimeout is the per-LLM-request timeout written into every router
	// config (default 1h). Injected from the LLM_REQUEST_TIMEOUT env var.
	LLMRequestTimeout time.Duration
	// ContextCompactionThreshold is the fraction of a provider's window at
	// which the router compacts the conversation (default 0.8, #47). Injected
	// from the CONTEXT_COMPACTION_THRESHOLD env var.
	ContextCompactionThreshold float64
	// ContextCompactionMode is "summary" (default) or "truncate", the rollback
	// switch (#47). Injected from the CONTEXT_COMPACTION_MODE env var.
	ContextCompactionMode string
	// ContextCompactionRatio is the fraction of the window drop-oldest
	// truncation cuts down to ("truncate" mode and the summary fallback).
	// Injected from the deprecated CONTEXT_COMPACTION_RATIO env var.
	ContextCompactionRatio float64

	// HindsightURL is the configured hindsight API endpoint (e.g. http://hindsight.local).
	// Injected from the HINDSIGHT_URL env var. Used to generate ipBlock egress rules
	// in the per-run NetworkPolicies when the cluster has a default-deny egress policy.
	HindsightURL string
	// HindsightAPIKey authenticates the model-router to a hindsight API that
	// requires a tenant API key. Injected from the HINDSIGHT_API_KEY env var; the
	// operator mirrors it into each run namespace (see ensureHindsightKeySecret).
	HindsightAPIKey string
	// OperatorNamespace is the namespace the operator runs in (POD_NAMESPACE). Per-run
	// NetworkPolicies allow its pods to scrape the model-router's :9091 metrics.
	OperatorNamespace string
	// Sandboxes is the OpenShell gateway that runs agents with
	// spec.runtime.sandbox set. Nil when the operator has no gateway configured;
	// such runs then fail with a clear reason.
	Sandboxes openshell.Gateway
	// SandboxPlacement chooses the nodes sandbox pods run on.
	SandboxPlacement openshell.Placement
	// Approvals stores egress approvals (PostgreSQL). Nil disables them: the
	// sandbox's denied requests stay denied.
	Approvals ApprovalStore
	// ApprovalNotifier tells approvers about new pending approvals. Optional.
	ApprovalNotifier ApprovalNotifier
	// GitHubApp mints the installation tokens of sandboxes with
	// spec.runtime.sandbox.github. Nil when no GitHub App is configured.
	GitHubApp GitHubTokenMinter
	// ClusterDomain is the cluster DNS domain (default "cluster.local"), used to
	// address the router Service from the sandbox namespace.
	ClusterDomain string
}

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

	// K8s reads the logs of container steps' pods. nil leaves their output empty.
	K8s kubernetes.Interface
	// Approvals stores the decisions of approval steps (the PostgreSQL store);
	// nil makes approval steps fail with a clear reason.
	Approvals ApprovalStore
	// ApprovalNotifier tells approvers about a new approval step. Optional.
	ApprovalNotifier ApprovalNotifier
	// CompletionNotifier announces workflows that opted in with the
	// notify-on-completion annotation when they finish. Optional.
	CompletionNotifier TextNotifier
	// AllowedRegistries restricts container steps' images, like the webhook does
	// for agents and tools. Empty allows any.
	AllowedRegistries []string
	// Sandboxes runs workflow-owned OpenShell sandboxes. Nil makes spec.sandbox
	// fail with a clear reason; workflows without one keep their existing behavior.
	Sandboxes openshell.Gateway
	// SandboxPlacement chooses the nodes workflow sandbox pods run on.
	SandboxPlacement openshell.Placement
	// GitHubApp mints optional credential-bound tokens for repository checkouts.
	GitHubApp GitHubTokenMinter
	// ClusterDomain is the cluster DNS domain used by sandboxed agent routers.
	ClusterDomain string
}

type ApprovalNotifier interface {
	NotifyApproval(ctx context.Context, a postgresql.Approval) error
}

type ApprovalStore interface {
	RequestApproval(ctx context.Context, a postgresql.Approval) (postgresql.Approval, error)
	ListApprovals(ctx context.Context, q postgresql.ApprovalQuery) ([]postgresql.Approval, error)
	DecideApproval(ctx context.Context, id, status, by, reason string) (postgresql.Approval, error)
	MarkApprovalApplied(ctx context.Context, id string) error
	WithdrawRunApprovals(ctx context.Context, namespace, runName string) error
	WithdrawBySourcePrefix(ctx context.Context, kind, prefix, reason string) error
}

type GitHubTokenMinter interface {
	InstallationToken(ctx context.Context, req githubapp.TokenRequest) (*githubapp.Token, error)
}

type KnowledgeBaseReconciler struct {
	client.Client
	Scheme           *runtime.Scheme
	MCPIngesterImage string
	QdrantImage      string
}

type MCPServerReconciler struct {
	client.Client
	Scheme *runtime.Scheme
}

type ModelProviderReconciler struct {
	client.Client
	Scheme *runtime.Scheme
}

type ModelSelectorReconciler struct {
	client.Client
	Scheme *runtime.Scheme
}

type TenantConfigReconciler struct {
	client.Client
	Scheme    *runtime.Scheme
	Refresher TenantRefresher
}

type TenantRefresher interface {
	RefreshTenants(ctx context.Context) error
}

type TextNotifier interface {
	NotifyText(ctx context.Context, text string) error
}

type ToolReconciler struct {
	client.Client
	Scheme *runtime.Scheme
}

type WebhookApprovalNotifier struct {
	URL string
	// UIURL is the UI's public base URL; messages link to its approvals inbox.
	UIURL string
	HTTP  *http.Client
}