pkg

type AgentConfiguration struct {
	// Assignee is the task frontmatter assignee value that routes to this agent.
	Assignee string
	// TaskType is the singular task_type value from ConfigSpec.TaskType.
	// Deprecated in favour of TaskTypes; stays functional.
	TaskType string
	// TaskTypes is the list of task_type values from ConfigSpec.TaskTypes.
	// Nil when the CRD only sets the singular TaskType field.
	TaskTypes []string
	// Image is the container image base name (without tag). Tag is appended at runtime from branch.
	Image string
	// Env holds per-agent environment variables (e.g. API keys, config).
	// These are merged with shared env vars (TASK_CONTENT, TASK_ID, KAFKA_BROKERS, BRANCH)
	// when spawning the K8s Job.
	Env map[string]string
	// VolumeClaim is the name of an existing PVC to mount into the container.
	// Empty means no volume mount.
	VolumeClaim string
	// VolumeMountPath is the container path where the PVC is mounted.
	// Required when VolumeClaim is set.
	VolumeMountPath string
	// SecretName is the name of a K8s Secret to mount as envFrom on the container.
	// Empty means no secret is mounted.
	SecretName string
	// Resources declares optional resource requests and limits for the agent container.
	// Nil means "do not set, keep the k8s builder default".
	Resources *agentv1.AgentResources
	// MaxConcurrentJobs caps how many Jobs this agent may run at once.
	// 0 means unlimited.
	MaxConcurrentJobs int
	// PriorityClassName is the Kubernetes PriorityClass name to stamp onto spawned Job PodTemplates.
	PriorityClassName string
	// ImagePullSecret is the name of the K8s Secret used for image pulls.
	// Empty uses the cluster default (typically "docker").
	ImagePullSecret string
	// Trigger declares the per-agent phase and status conditions under which the executor spawns a Job.
	Trigger *agentv1.Trigger
	// ZombieJobTimeoutSeconds mirrors ConfigSpec.ZombieJobTimeoutSeconds. The
	// spawner stamps this value onto Job.Spec.ActiveDeadlineSeconds; the sweeper
	// uses it as the elapsed-time threshold. nil means "use the default
	// DefaultZombieJobTimeoutSeconds from the CRD types package".
	ZombieJobTimeoutSeconds *int32
}

type AgentConfigurations []AgentConfiguration

type CRDClientBuilder func(*rest.Config) (apiextensionsclient.Interface, error)

type ConfigResolver interface {
	Resolve(ctx context.Context, assignee string) (AgentConfiguration, error)
}

type CronScheduler interface {
	Run(ctx context.Context) error
}

type EventHandlerConfig k8s.EventHandler[agentv1.Config]

type JobWatcher interface {
	// Run starts the Job and Pod informers and blocks until ctx is cancelled.
	Run(ctx context.Context) error
	// HandleJob processes a single Job (invoked by the informer event handlers
	// and by unit tests directly, avoiding the need for a fake informer).
	HandleJob(ctx context.Context, job *batchv1.Job)
	// HandlePod processes a single Pod (invoked by the Pod informer event handler
	// and by unit tests directly).
	HandlePod(ctx context.Context, pod *corev1.Pod)
	// PodLister returns the Pod lister backed by the shared informer cache, for
	// use by the deadline sweeper. The returned lister is safe for concurrent
	// read access.
	PodLister() corev1listers.PodLister
}

type K8sConnector interface {
	SetupCustomResourceDefinition(ctx context.Context) error
	Listen(
		ctx context.Context,
		namespace libk8s.Namespace,
		handler cache.ResourceEventHandler,
	) error
}

type ResultPublisher interface {
	// PublishSpawnNotification publishes current_job, job_started_at, and
	// spawn_notification without touching any other frontmatter keys.
	PublishSpawnNotification(ctx context.Context, task lib.Task, jobName string) error
	// PublishFailure publishes a zombie failure: clears current_job and atomically
	// bumps trigger_count by 1 via a paired IncrementFrontmatterCommand. Leaves
	// phase, status, and assignee untouched so the existing trigger_count retry
	// cap (applyTriggerCap in task/controller/pkg/result/result_writer.go) handles
	// eventual operator-inbox escalation. Idempotent per current_job via a TTL'd
	// LRU; concurrent classifications for the same job emit one event.
	PublishFailure(ctx context.Context, task lib.Task, jobName string, reason string) error
	// PublishClearCurrentJob clears current_job in the vault task frontmatter
	// (writes "" only — no body section, no trigger_count bump, no status/phase
	// touch). Used on the job-success path, where the agent already published its
	// real result and the task is about to be evicted from the TaskStore: without
	// this clear, a succeeded job leaves current_job/job_started_at set forever
	// (the zombie sweeper is blind to it because the task left Snapshot()). The
	// write is idempotent (empty → empty is a no-op visually) and deduped per
	// jobName by the same TTL'd LRU as PublishFailure, so the informer's repeated
	// terminal re-deliveries do not spam Kafka.
	PublishClearCurrentJob(ctx context.Context, task lib.Task, jobName string) error
	// PublishIncrementTriggerCount sends an IncrementFrontmatterCommand that atomically
	// increments trigger_count by 1. Must complete before SpawnJob is called.
	PublishIncrementTriggerCount(ctx context.Context, task lib.Task) error
	// PublishSetTriggerScope sends an UpdateFrontmatterCommand that records a
	// trigger_scope and sets trigger_count to count, in one atomic write. Called
	// instead of PublishIncrementTriggerCount in the two cases where the scope
	// itself has to be written:
	//
	//   - the scope CHANGED (count 1): a re-dispatch against a new phase or a new
	//     ref starts from a fresh budget, counting the spawn about to happen.
	//   - the scope was ABSENT (count = existing trigger_count + 1): the task
	//     predates the field and adopts the current scope WITHOUT a budget reset.
	//     Absent must not be treated as changed — every task in flight today has no
	//     trigger_scope, so resetting on absence would hand each of them a free
	//     budget on the first event after deploy, including one already at cap.
	//
	// This is an UpdateFrontmatterCommand rather than a result publish on purpose.
	// trigger_count is controller-owned: the result writer's ownership guard
	// (MergeFrontmatter in task/controller) discards any incoming counter value, so
	// a reset routed through a result payload would be silently dropped. The atomic
	// frontmatter commands take a different path (buildUpdateModifyFn), which applies
	// Updates directly to the on-disk frontmatter — an explicit, intentional write
	// rather than a stale spawn-time snapshot.
	PublishSetTriggerScope(ctx context.Context, task lib.Task, scope string, count int) error
	// PublishTypeMismatchFailure publishes a synthetic failure when the task's task_type
	// is not in the agent's effective type set. Clears assignee and current_job so the
	// task surfaces in the operator inbox via assignee=="" filter. Does not bump
	// trigger_count or retry_count.
	PublishTypeMismatchFailure(ctx context.Context, task lib.Task, reason string) error
	// PublishRaw publishes a raw payload for testing error paths.
	PublishRaw(ctx context.Context, operation base.CommandOperation, payload interface{}) error
}

type TaskStore struct {
	// contains filtered or unexported fields
}

type ZombieReason string

type ZombieSweeper interface {
	// Run blocks until ctx is cancelled. Each tick (interval sourced from the
	// first non-nil ConfigSpec.ZombieSweeperIntervalSeconds across the resolver's
	// configs, else DefaultZombieSweeperIntervalSeconds) it calls SweepOnce.
	Run(ctx context.Context) error
	// SweepOnce performs a single sweep pass. Exposed for unit tests so they
	// do not have to manage tickers. Returns an error only on context
	// cancellation paths; per-task classification errors are logged.
	SweepOnce(ctx context.Context) error
}