pkg

type AgentCardConfig struct {
	// Name names the deployed agent in the Agent Card.
	Name string
	// PublicURL is the externally reachable A2A endpoint the card advertises verbatim.
	// It is never derived from the listen address or a request header.
	PublicURL string
}

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

type Backend string

type BackendProvider interface {
	// Get returns the backend serving the named backend, or an error when the name is
	// not one the controller knows or its implementation is not wired.
	Get(ctx context.Context, backend Backend) (WorkerBackend, error)
}

type ControlRequest struct {
	Operation Operation `json:"operation"`
	// Create is set when Operation is OperationCreate.
	Create *CreateRequest `json:"create,omitempty"`
	// Stop is set when Operation is OperationStop.
	Stop *StopRequest `json:"stop,omitempty"`
}

type ControlResponse struct {
	Operation Operation       `json:"operation"`
	Create    *CreateResponse `json:"create,omitempty"`
	List      *ListResponse   `json:"list,omitempty"`
	Stop      *StopResponse   `json:"stop,omitempty"`
}

type CreateRequest struct {
	Task TaskName `json:"task"`
	// Env carries extra environment for the worker, keyed by variable name. It is how a
	// caller hands a worker the settings its own tooling needs — the attention store's URL
	// and token, for instance.
	//
	// ⚠️ Every entry travels through the child environment, never in argv, because the
	// controller cannot tell a credential from a plain setting and create is a public
	// surface. A name colliding with one of the controller's own settings is refused rather
	// than merged: silently overriding AGENT_TYPE would start a worker outside the gated
	// service path, which is the setting its permission gate depends on.
	Env map[string]string `json:"env,omitempty"`
	// Mounts are the host paths the caller asks the controller to make reachable. Each is
	// checked against the controller's allowlist before any container is created.
	Mounts []Mount `json:"mounts,omitempty"`
	// Secrets are the credentials the caller asks the controller to resolve and deliver.
	// Only the TeamVault KEY travels here; the value is resolved controller-side.
	Secrets []Secret `json:"secrets,omitempty"`
}

type CreateResponse struct {
	Worker Worker `json:"worker"`
	// Token is the worker's own bearer credential. It must never be logged, echoed into a
	// transcript, or written to a file.
	Token string `json:"token"`
}

type DockerClient interface {
	// Run runs docker with args and the extra environment, returning its standard output.
	// The extra environment is layered on the caller's own and is where a credential
	// travels, so the value never reaches argv.
	Run(ctx context.Context, args []string, extraEnv []string) (string, error)
}

type DockerConfig struct {
	// Image is the image every worker container runs.
	Image string
	// AgentNameBase prefixes the Agent Card name each worker advertises.
	AgentNameBase string
	// Model is the model the worker's turns run against.
	Model string
	// AllowedTools is the tool allow-list the worker's agent runs with.
	AllowedTools string
	// PortStart and PortEnd bound the host ports the backend will publish on.
	PortStart int
	PortEnd   int
	// MountAllowlist is the set of host paths a caller may ask this backend to expose. Its
	// zero value allows nothing, so a backend built without it refuses every mount — see
	// MountAllowlist for why the empty default is the safe one here.
	MountAllowlist MountAllowlist
	// TeamVault resolves a declared secret's key to its value. A nil resolver refuses any
	// create that declares a secret, rather than starting a worker whose secret is missing.
	TeamVault TeamVaultResolver
	// SecretDir is the host directory the resolved secret files are written into before being
	// bind-mounted read-only into the worker. It must be private to this controller: every file
	// in it holds a credential, and one controller's workers must never be able to read
	// another's.
	SecretDir string
}

type EgressDestination struct {
	Namespace string
	PodLabels map[string]string
	Port      int32
}

type KubernetesClient interface {
	// GetConfig returns the named Config.
	GetConfig(ctx context.Context, name string) (*agentv1.Config, error)
	// ListConfigs returns every Config matching labelSelector.
	ListConfigs(ctx context.Context, labelSelector string) ([]agentv1.Config, error)
	// CreateConfig creates config and returns it as stored, carrying its uid.
	CreateConfig(ctx context.Context, config *agentv1.Config) (*agentv1.Config, error)
	// DeleteConfig deletes the named Config. Its owned objects are garbage-collected.
	DeleteConfig(ctx context.Context, name string) error
	// GetSecret returns the named Secret.
	GetSecret(ctx context.Context, name string) (*corev1.Secret, error)
	// CreateSecret creates secret.
	CreateSecret(ctx context.Context, secret *corev1.Secret) error
	// CreateService creates service.
	CreateService(ctx context.Context, service *corev1.Service) error
	// CreateIngress creates ingress.
	CreateIngress(ctx context.Context, ingress *networkingv1.Ingress) error
	// CreateNetworkPolicy creates policy.
	CreateNetworkPolicy(ctx context.Context, policy *networkingv1.NetworkPolicy) error
}

type KubernetesConfig struct {
	// Namespace is where every worker Config, Secret, Service and Ingress is written.
	Namespace string
	// TemplateConfig names the Config every worker is cloned from.
	TemplateConfig string
	// AgentNameBase prefixes the name each worker's Agent Card advertises.
	AgentNameBase string
	// IngressDomain is the parent domain of every worker host, so a worker named
	// a2a-worker-<id> is served at https://a2a-worker-<id>.<IngressDomain>/a2a.
	IngressDomain string
	// IngressClassName is the ingress class every worker Ingress uses.
	IngressClassName string
	// TLSSecretName names the wildcard certificate Secret covering IngressDomain.
	TLSSecretName string
	// WorkerPriorityClass is the PriorityClass every worker pod runs under. Empty keeps the
	// template's class. It exists because a class carries its own ResourceQuota on the cluster:
	// workers that inherited the template's class would share the template's pod cap, which the
	// template's own pod already fills.
	WorkerPriorityClass string
	// EgressAllow lists the in-cluster destinations each worker's NetworkPolicy allows, on top
	// of DNS. Everything else — the public internet included — is denied.
	EgressAllow []EgressDestination
	// TeamVault resolves a declared secret's key to its value. A nil resolver refuses any
	// create that declares a secret, rather than writing a Config whose pod would start
	// without the credential it was told to expect.
	TeamVault TeamVaultResolver
}

type ListResponse struct {
	Workers []Worker `json:"workers"`
}

type LocalConfig struct {
	// VaultDir is the vault root the workers' task files live in. It is also the directory
	// each worker's tab starts in, so the worker runs where its task lives.
	VaultDir string
	// ClaudeScript is the absolute path to the vault's claude_script launcher — the `cc-*`
	// script every worker's tab execs.
	ClaudeScript string
	// WindowID names the WezTerm window a worker's tab opens in, from LOCAL_WINDOW_ID. Empty
	// omits the flag entirely, and the tab then lands in the window the spawning process is
	// associated with — which under launchd is the default window. It exists because the flag
	// is part of the spawn this backend mirrors; the controller has no role map to resolve one
	// from, so it is configured rather than derived.
	WindowID string
}

type LocalWorker struct {
	WorkerID WorkerID `json:"worker_id"`
	Task     TaskName `json:"task"`
	// PaneID is the WezTerm pane the worker runs in. It is the worker's only handle.
	PaneID string `json:"pane_id"`
	// GuiID names the WezTerm GUI instance the pane belongs to: the live GUI socket's path,
	// which carries the GUI process's own pid. It is what makes PaneID an identity rather than
	// a bare counter — a pane id restarts from a low number when the mux is recreated, so after
	// a GUI restart a stale entry's id can name a pane this controller never opened.
	GuiID string `json:"gui_id"`
	// SessionID is the Claude Code session the worker's tab bound to the task, empty until
	// that binding lands.
	SessionID string `json:"session_id"`
	// CreateSessionID is the session id the task file ALREADY CARRIED when this worker was
	// created — in practice the id of an earlier session of the same task, because this
	// worker's own session cannot have started before its tab did.
	//
	// ⚠️ IT EXISTS SO THAT AN EARLIER SESSION'S ID IS NEVER REPORTED AS THIS WORKER'S. The
	// task-scoped `claude_session_id` frontmatter field is stamped by the vault when it is
	// empty and LEFT ALONE on every later binding, so once a worker has been stopped and
	// another created for the same task, the file still names the STOPPED worker's session —
	// and nothing ever rewrites it, so that value would otherwise be permanent. The snapshot
	// is what refreshSessionIDs measures against: a value that was already there when this
	// worker started cannot be its own, and a value that appeared afterwards can.
	CreateSessionID string `json:"create_session_id"`
}

type Mount struct {
	// HostPath is the absolute host path to expose. It must fall inside the controller's
	// configured allowlist, or the create is refused.
	HostPath string `json:"host_path,omitempty"`
	// Volume is a named docker volume. Refused, always, in this revision.
	Volume string `json:"volume,omitempty"`
	// ContainerPath is where the path appears inside the worker. Required.
	ContainerPath string `json:"container_path"`
	// ReadOnly asks for the mount to be read-only. Defaults to false, so a caller that wants
	// a read-only mount must say so.
	ReadOnly bool `json:"read_only,omitempty"`
}

type MountAllowlist []string

type Operation string

type PortProber interface {
	// IsFree reports whether port can be bound on the host.
	IsFree(ctx context.Context, port int) bool
}

type ResolvedSecret struct {
	Name  string
	Value string
}

type Secret struct {
	// Name is the key the worker reads the secret under. Required.
	Name string `json:"name"`
	// TeamVaultKey is the TeamVault lookup key the controller resolves. A short identifier
	// rather than a secret, which is what makes naming it here safe.
	TeamVaultKey string `json:"teamvault_key"`
}

type SecretMount struct {
	// HostPath is the 0600 file on the host holding the value.
	HostPath string
	// Name is the declared name; the file appears at SecretContainerDir/<Name> in the worker.
	Name string
}

type StopRequest struct {
	WorkerID WorkerID `json:"worker_id"`
}

type StopResponse struct {
	Worker Worker `json:"worker"`
}

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

type TaskName string

type TeamVaultResolver interface {
	// Resolve returns the value for key. The returned value is a secret: it must never be
	// logged, echoed into a transcript, or written to a file. An error names the KEY and the
	// CLI's own stderr, never the value.
	Resolve(ctx context.Context, key string) (string, error)
}

type WeztermClient interface {
	// GuiID returns an identifier for the GUI instance the other three calls talk to — the
	// live GUI socket's path, which carries the GUI process's own pid. It differs after a GUI
	// restart, and that is the whole point of recording it: a pane id on its own is a per-mux
	// counter that restarts with the mux, so only a GUI id makes it interpretable.
	//
	// ⚠️ IT IS RESOLVED ONCE PER BACKEND CALL AND THEN PASSED TO EVERY OTHER METHOD, RATHER
	// THAN RESOLVED AGAIN INSIDE EACH. The resolution picks the NEWEST live socket, so two
	// resolutions within one call can name two different GUIs, and a GUI that restarts between
	// them would have a pane opened in one GUI recorded under the other's identity — which is
	// the single thing the recorded identity exists to prevent.
	GuiID(ctx context.Context) (string, error)
	// Spawn opens a tab running inner as `bash -lc inner`, in the GUI guiID names, in the
	// window windowID names when it is not empty, and returns the new pane's id.
	Spawn(ctx context.Context, guiID string, windowID string, inner string) (string, error)
	// PaneIDs returns the id of every pane the GUI guiID names has.
	PaneIDs(ctx context.Context, guiID string) ([]string, error)
	// KillPane closes the pane paneID names in the GUI guiID names.
	KillPane(ctx context.Context, guiID string, paneID string) error
}

type Worker struct {
	WorkerID WorkerID    `json:"worker_id"`
	Task     TaskName    `json:"task"`
	A2AURL   string      `json:"a2a_url"`
	Backend  Backend     `json:"backend"`
	State    WorkerState `json:"state"`
	// PaneID is the WezTerm pane the worker runs in. Empty unless the worker runs in a tab.
	PaneID string `json:"pane_id"`
	// SessionID is the Claude Code session the worker's tab is bound to. Empty unless the
	// worker runs in a tab, and empty there too until the session's own task binding lands.
	SessionID string `json:"session_id"`
}

type WorkerBackend interface {
	// Create starts one worker serving the requested task and returns it together with
	// its own bearer token. ⚠️ A task that already has a worker is REFUSED, naming that
	// worker's id, rather than answered: only one worker is ever started per task, and the
	// existing worker's token cannot be returned because the backend kept no copy of it —
	// so a success reply would name a worker no caller could authenticate to, which reads
	// as a working worker while being unreachable. The caller's recovery is to stop the
	// named worker and create again.
	Create(ctx context.Context, req CreateRequest) (*CreateResponse, error)

	// List returns every worker the backend owns. It is rebuilt from the backend's own
	// resource state on every call, never from controller memory, so a controller
	// restart loses nothing.
	List(ctx context.Context) (*ListResponse, error)

	// Stop stops and removes the named worker and returns it.
	Stop(ctx context.Context, req StopRequest) (*StopResponse, error)
}

type WorkerID string

type WorkerResourceBuilder interface {
	// BuildConfig clones template into the Config for one worker serving task.
	BuildConfig(template agentv1.Config, workerID WorkerID, task TaskName) *agentv1.Config
	// BuildSecret renders the worker's credential Secret, owned by owner: every key of
	// template, with the bearer replaced by token, plus one entry per declared secret.
	BuildSecret(
		owner agentv1.Config,
		template corev1.Secret,
		token string,
		secrets []ResolvedSecret,
	) *corev1.Secret
	// BuildService renders the ClusterIP Service in front of owner's pod.
	BuildService(owner agentv1.Config) *corev1.Service
	// BuildIngress renders the TLS Ingress that exposes owner's Service on its own host.
	BuildIngress(owner agentv1.Config) *networkingv1.Ingress
	// BuildNetworkPolicy renders the egress NetworkPolicy that confines owner's pod.
	BuildNetworkPolicy(owner agentv1.Config) *networkingv1.NetworkPolicy
	// A2AURL is the address the worker named name advertises.
	A2AURL(name string) string
}

type WorkerState string

type WorkerStore interface {
	// List returns every worker the store holds, empty when the store does not exist yet.
	List(ctx context.Context) ([]LocalWorker, error)
	// Save replaces the store's contents with workers.
	Save(ctx context.Context, workers []LocalWorker) error
}