agents

type Agent struct {
	Name      string `json:"name"`
	Namespace string `json:"namespace"`
	// Target is the workload cluster the agent runs on; absent on the
	// installation's own cluster.
	Target
	// Exists is false while the HelmRelease has not rendered the
	// AgentTemplate yet (or failed to).
	Exists        bool   `json:"exists"`
	DisplayName   string `json:"displayName,omitempty"`
	Description   string `json:"description,omitempty"`
	ModelConfig   string `json:"modelConfig,omitempty"`
	IconURL       string `json:"iconUrl,omitempty"`
	SystemMessage string `json:"systemMessage,omitempty"`
	// Skills as pinned: git skills by commit, OCI skills by digest.
	Skills Skills `json:"skills,omitempty"`
	// Toolset is the toolset the agent declares: the owning HelmRelease's
	// `toolset` value, or — for a bare AgentTemplate — the X-Muster-Toolset
	// header of the agent's RemoteMCPServer. Absent when none is declared.
	Toolset []string `json:"toolset,omitempty"`
	// ImplicitFullAccess is true when the agent declares no toolset but binds
	// muster: its meta-tools see every tool the gateway exposes to the
	// caller. Such agents predate toolsets and still need one assigned.
	ImplicitFullAccess bool `json:"implicitFullAccess,omitempty"`
	// Tools are the template's MCP bindings.
	Tools []ToolBinding `json:"tools,omitempty"`
	// Ready is the platform Harness's verdict on the template (Ready and the
	// desired revision is the latest successful one); nil while the template
	// is absent or the Harness has not reported.
	Ready *bool `json:"ready"`
	// Harnesses is the template's per-Harness status.
	Harnesses []HarnessStatus `json:"harnesses,omitempty"`
	// Managed is helmrelease, gitops or none.
	Managed     string          `json:"managed"`
	HelmRelease *HelmReleaseRef `json:"helmRelease,omitempty"`
	// Values are the HelmRelease's inline values (the chart contract), when a
	// HelmRelease owns the agent.
	Values map[string]any `json:"values,omitempty"`
}

type ChartRef struct {
	Kind      string `json:"kind"`
	Name      string `json:"name"`
	Namespace string `json:"namespace,omitempty"`
}

type ChartSource interface {
	SchemaSource
	Info(ctx context.Context) chart.Info
	Name() string
	OCIURL() string
	SemverRange() string
}

type CommitFile struct {
	Path    string `json:"path"`
	Action  string `json:"action"`
	Content string `json:"content,omitempty"`
}

type CommitResult struct {
	// Repository is owner/name, Base the branch the change goes to.
	Repository string `json:"repository"`
	Base       string `json:"base"`
	// Directory is where the files go: CommitDirectory under the
	// Kustomization's path (or the path the caller named).
	Directory string `json:"directory"`
	// Kustomization is the Flux Kustomization (namespace/name) that lands
	// the files after the merge, and Prune its spec.prune. Empty for a target
	// the caller named.
	Kustomization string `json:"kustomization,omitempty"`
	Prune         bool   `json:"prune"`
	// Branch is the pull request's head branch.
	Branch string       `json:"branch"`
	Files  []CommitFile `json:"files"`
	// PullRequest is the URL of the pull request opened as the caller, empty
	// on a dry run and when nothing changes.
	PullRequest string `json:"pullRequest,omitempty"`
	Number      int    `json:"number,omitempty"`
	// Author is the GitHub login the pull request is opened as.
	Author string `json:"author,omitempty"`
	// LiveSteps are what the merge alone does not do on the installation.
	LiveSteps []string `json:"liveSteps,omitempty"`
}

type ComposeConfig struct {
	// ChartOCIURL is the agent chart, e.g. oci://gsoci.azurecr.io/charts/giantswarm/agent.
	ChartOCIURL string
	// ChartName is the OCIRepository's name (the chart name).
	ChartName string
	// ChartSemver is the OCIRepository ref.semver range (1.x).
	ChartSemver string
	// ChartSemverFilter is the OCIRepository ref.semverFilter: the regular
	// expression the tags must match before the range is evaluated. Empty
	// composes none.
	ChartSemverFilter string
	// HelmReleaseInterval / OCIRepositoryInterval are the Flux intervals.
	HelmReleaseInterval   string
	OCIRepositoryInterval string
	// ServiceAccountName is HelmRelease.spec.serviceAccountName, required by a
	// Flux multi-tenancy admission policy in tenant namespaces; empty omits it.
	ServiceAccountName string
	// HelmReleaseAPIVersion / OCIRepositoryAPIVersion are the served Flux API
	// versions (helm.toolkit.fluxcd.io/v2, source.toolkit.fluxcd.io/v1).
	HelmReleaseAPIVersion   string
	OCIRepositoryAPIVersion string
	// MusterURL is the platform's muster MCP URL, composed as the chart value
	// muster.url; empty composes nothing and the chart default applies.
	MusterURL string
	// TargetMusterURL is the muster MCP URL composed into an agent on a
	// workload cluster: one those clusters reach (the installation's public
	// endpoint). Empty: agents are refused a target cluster.
	TargetMusterURL string
	// HarnessName is the platform Harness every agent runs on: composed as
	// the chart value agent.harness (the admission label's value), and the
	// status.harnesses[] entry that decides an agent's readiness.
	HarnessName string
	// SkillsGitAuthSecretName is the installation's skills credential: the
	// Secret (key `token`) in the agent's namespace that every agent with a
	// git skill reads its skills with, unless the agent names its own.
	// Empty: such agents fetch anonymously.
	SkillsGitAuthSecretName string
}

type Condition struct {
	Type               string `json:"type"`
	Status             string `json:"status"`
	Reason             string `json:"reason,omitempty"`
	Message            string `json:"message,omitempty"`
	LastTransitionTime string `json:"lastTransitionTime,omitempty"`
	ObservedGeneration int64  `json:"observedGeneration,omitempty"`
}

type Config struct {
	// DefaultNamespace receives agents when a request names none.
	DefaultNamespace string
	// ManagedNamespaces are the namespaces the service may read and write
	// (RBAC exists there); DefaultNamespace is always included.
	ManagedNamespaces []string
	// Compose is the platform side of the manifests.
	Compose ComposeConfig
	// KagentAPIVersion is the served kagent.dev version (v1alpha3).
	KagentAPIVersion string
	// Version is the service version reported by GET /info.
	Version string
	// GitHub offers commit mode: the pull request is opened as the person
	// with the GitHub token the App-pinned registration carries. Nil: commit
	// mode is refused as unsupported.
	GitHub RemoteFor
	// SkillsBootSecret keeps the installation's skills credential Secret
	// filled with the skills GitHub App's token; nil: the Secret is
	// provisioned by someone else.
	SkillsBootSecret *skills.BootSecret
}

type CreateResult struct {
	Agent     Agent     `json:"agent"`
	Manifests Manifests `json:"manifests"`
	// Created says which objects were new; the OCIRepository is shared per
	// namespace and reused when it exists.
	Created struct {
		OCIRepository bool `json:"ociRepository"`
		HelmRelease   bool `json:"helmRelease"`
	} `json:"created"`
	Status *Status `json:"status,omitempty"`
	// RequestedBy is the authenticated caller the write ran as (email, else
	// subject); empty when the server runs without OAuth.
	RequestedBy string `json:"requestedBy,omitempty"`
	WriteOutcome
}

type DeleteResult struct {
	Name      string `json:"name"`
	Namespace string `json:"namespace"`
	Target
	HelmReleaseDeleted bool `json:"helmReleaseDeleted"`
	// AgentTemplateDeleted: the template was deleted directly (a bare one, or
	// the rendered objects of a suspended release, both with force).
	AgentTemplateDeleted   bool `json:"agentTemplateDeleted"`
	RemoteMCPServerDeleted bool `json:"remoteMcpServerDeleted"`
	OCIRepositoryDeleted   bool `json:"ociRepositoryDeleted"`
	// OCIRepositoryKept explains why the chart source stays (other agents
	// reference it, or it could not be checked).
	OCIRepositoryKept string `json:"ociRepositoryKept,omitempty"`
	// RequestedBy is the authenticated caller the delete ran as.
	RequestedBy string `json:"requestedBy,omitempty"`
	WriteOutcome
}

type Event struct {
	Type    string `json:"type"`
	Reason  string `json:"reason"`
	Message string `json:"message"`
	Object  string `json:"object"`
	Count   int32  `json:"count,omitempty"`
	Last    string `json:"lastTimestamp,omitempty"`
}

type GitHubRemote interface {
	commit.Remote
	commit.Reader
}

type GitSkill struct {
	// URL of the git repository (http or https).
	URL string `json:"url"`
	// Ref is a branch, tag or commit a write resolves to its head commit at
	// write time; empty (and no Commit) means the repository's default
	// branch. Never written: the pin is Commit.
	Ref string `json:"ref,omitempty"`
	// Commit is the full commit id (40 or 64 hex characters) the skill is
	// pinned to. Given by a caller who has one (list_skills reports it),
	// resolved from Ref otherwise.
	Commit string `json:"commit,omitempty"`
}

type HarnessStatus struct {
	Harness string `json:"harness"`
	// Ready / Accepted / ResolvedRefs / Compatible mirror the conditions; nil
	// while unreported.
	Ready        *bool `json:"ready"`
	Accepted     *bool `json:"accepted"`
	ResolvedRefs *bool `json:"resolvedRefs"`
	Compatible   *bool `json:"compatible"`
	// DesiredRevision is the revision compiled from the current generation;
	// LatestSuccessfulRevision the last one that became ready.
	DesiredRevision          string      `json:"desiredRevision,omitempty"`
	LatestSuccessfulRevision string      `json:"latestSuccessfulRevision,omitempty"`
	Conditions               []Condition `json:"conditions,omitempty"`
	// Warnings are the Harness's non-blocking compatibility decisions.
	Warnings []string `json:"warnings,omitempty"`
}

type HelmReleaseHistory struct {
	Version      int64  `json:"version"`
	ChartVersion string `json:"chartVersion,omitempty"`
	Status       string `json:"status,omitempty"`
	LastDeployed string `json:"lastDeployed,omitempty"`
}

type HelmReleaseRef struct {
	Name      string `json:"name"`
	Namespace string `json:"namespace"`
	// Ready mirrors the Ready condition; nil while unreported.
	Ready   *bool  `json:"ready"`
	Reason  string `json:"reason,omitempty"`
	Message string `json:"message,omitempty"`
	// ChartVersion is the deployed chart version (last history entry), else
	// the last attempted revision.
	ChartVersion          string `json:"chartVersion,omitempty"`
	LastAttemptedRevision string `json:"lastAttemptedRevision,omitempty"`
	Suspended             bool   `json:"suspended"`
	GitOpsOwned           bool   `json:"gitOpsOwned"`
	// Deleting is true while helm-controller uninstalls the release (the
	// HelmRelease carries a deletionTimestamp); the template disappears with
	// it.
	Deleting bool      `json:"deleting"`
	ChartRef *ChartRef `json:"chartRef,omitempty"`
}

type HelmReleaseStatus struct {
	Exists                bool                 `json:"exists"`
	Ready                 *bool                `json:"ready"`
	Suspended             bool                 `json:"suspended"`
	GitOpsOwned           bool                 `json:"gitOpsOwned"`
	Deleting              bool                 `json:"deleting"`
	Conditions            []Condition          `json:"conditions,omitempty"`
	History               []HelmReleaseHistory `json:"history,omitempty"`
	LastAttemptedRevision string               `json:"lastAttemptedRevision,omitempty"`
}

type InfoResponse struct {
	Version string     `json:"version"`
	Chart   chart.Info `json:"chart"`
	// Namespaces the service manages agents in.
	Namespaces struct {
		Default string   `json:"default"`
		Managed []string `json:"managed"`
	} `json:"namespaces"`
	// Capabilities are explicit flags; a false flag means the matching
	// operation answers 501 unsupported (or, for commit, that the mode does
	// not exist on this installation).
	Capabilities map[string]bool `json:"capabilities"`
	// Identity says how calls reach the API server: `caller` (every call
	// presents the signed-in user's IdP token; the user's RBAC governs) or
	// `serviceAccount` (the service's own identity behind a trusted proxy).
	Identity string `json:"identity"`
	// APIVersions are the served CRD versions the service composes and reads.
	APIVersions struct {
		AgentTemplate   string `json:"agentTemplate"`
		Harness         string `json:"harness"`
		RemoteMCPServer string `json:"remoteMcpServer"`
		ModelConfig     string `json:"modelConfig"`
		HelmRelease     string `json:"helmRelease"`
		OCIRepository   string `json:"ociRepository"`
	} `json:"apiVersions"`
	// Flux settings the composed HelmReleases carry.
	Flux struct {
		HelmReleaseInterval   string `json:"helmReleaseInterval"`
		OCIRepositoryInterval string `json:"ociRepositoryInterval"`
		ServiceAccountName    string `json:"serviceAccountName,omitempty"`
	} `json:"flux"`
	// Harness is the platform Harness every agent runs on.
	Harness struct {
		Name string `json:"name"`
	} `json:"harness"`
	// Muster is the platform's muster MCP gateway as composed into every
	// agent: URL empty means the chart default applies.
	Muster struct {
		URL string `json:"url"`
		// TargetURL is the muster URL composed into agents on workload
		// clusters; empty: target clusters are refused.
		TargetURL string `json:"targetUrl,omitempty"`
	} `json:"muster"`
	// SkillsRepositories are the configured skill repositories.
	SkillsRepositories []string `json:"skillsRepositories"`
	// SkillsGitAuthSecretName is the installation's skills credential Secret
	// (key token) an agent with a git skill fetches with unless it names its
	// own; empty: anonymous fetches.
	SkillsGitAuthSecretName string `json:"skillsGitAuthSecretName,omitempty"`
	// SkillsGitAuthMint is the state of that Secret when agent-manager keeps
	// it filled with the skills GitHub App's token: the last refresh, the
	// token's expiry and a failed refresh's error.
	SkillsGitAuthMint *skills.BootSecretStatus `json:"skillsGitAuthMint,omitempty"`
}

type Location struct {
	Namespace string `json:"namespace,omitempty"`
	Target
}

type Manifests struct {
	OCIRepository string         `json:"ociRepository"`
	HelmRelease   string         `json:"helmRelease"`
	Values        map[string]any `json:"values"`
}

type ModelConfig struct {
	Name      string `json:"name"`
	Namespace string `json:"namespace"`
	Provider  string `json:"provider,omitempty"`
	Model     string `json:"model,omitempty"`
	// Accepted mirrors the kagent Accepted condition; nil while unreported.
	Accepted  *bool  `json:"accepted"`
	Message   string `json:"message,omitempty"`
	ManagedBy string `json:"managedBy,omitempty"`
}

type RemoteFor func(token string) (GitHubRemote, error)

type SchemaSource interface {
	Schema(ctx context.Context) chart.Schema
}

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

type Skill struct {
	// Name is the skill's name under the template (spec.skills[].name), the
	// directory it mounts under; defaults to the last path segment, else the
	// repository name. Unique per agent.
	Name string `json:"name,omitempty"`
	// Path is the subdirectory holding SKILL.md (git skills); empty for the
	// repository root. Relative, without "..".
	Path string `json:"path,omitempty"`
	// Git is the git source.
	Git *GitSkill `json:"git,omitempty"`
	// OCI is the OCI source: <registry>/<repository>@sha256:<digest> once
	// written; a write also takes <registry>/<repository>:<tag> and resolves
	// the digest.
	OCI string `json:"oci,omitempty"`
}

type SkillPinner interface {
	// GitHead resolves ref of repoURL (empty: the default branch) to a commit.
	GitHead(ctx context.Context, repoURL, ref string) (string, error)
	// OCIDigest pins an OCI reference to <repository>@sha256:<digest>.
	OCIDigest(ctx context.Context, ref string) (string, error)
	// RequireReadable refuses a repository login (the caller's GitHub login,
	// empty when unknown) cannot read: skills.ErrNotReadable.
	RequireReadable(ctx context.Context, repoURL, login string) error
}

type Skills []Skill

type Spec struct {
	// Location is the agent's namespace (empty selects the default managed
	// namespace) and, to run it on a workload cluster, the target cluster.
	// Fixed at create.
	Location
	// Name is the DNS-1123 technical name: the HelmRelease name and the
	// AgentTemplate name. The caller confirms it; agent-manager never derives
	// it.
	Name string `json:"name"`
	// DisplayName is the friendly Unicode name (max 63 chars).
	DisplayName string `json:"displayName,omitempty"`
	// Description goes to AgentTemplate.spec.description.
	Description string `json:"description,omitempty"`
	// SystemMessage is the system prompt (spec.systemPrompt); empty keeps the
	// chart default. At most MaxSystemMessageLength characters.
	SystemMessage string `json:"systemMessage,omitempty"`
	// ModelConfig names an existing kagent ModelConfig in the namespace.
	ModelConfig string `json:"modelConfig"`
	// Harness names the Harness of the namespace that runs the agent (chart
	// agent.harness); empty selects the platform Harness. Fixed at create.
	Harness string `json:"harness,omitempty"`
	// IconURL is the avatar URL (chart agent.iconUrl, rendered as the
	// ui.giantswarm.io/icon-url annotation).
	IconURL string `json:"iconUrl,omitempty"`
	// Skills the agent mounts; every entry is pinned before it is written.
	Skills Skills `json:"skills,omitempty"`
	// GitAuthSecretName names the Secret in the agent's namespace whose key
	// `token` reads the agent's private git skills (chart value
	// skillsGitAuthSecretRef.name, fanned out to every git skill). Empty
	// selects the installation's (ComposeConfig.SkillsGitAuthSecretName).
	GitAuthSecretName string `json:"gitAuthSecretName,omitempty"`
	// Toolset is the list of selectors that bounds which of the gateway's
	// tools the agent can use (chart value `toolset`). Required on create;
	// see ValidateToolset for the grammar.
	Toolset []string `json:"toolset,omitempty"`
	// Labels / Annotations are merged onto the AgentTemplate by the chart.
	Labels      map[string]string `json:"labels,omitempty"`
	Annotations map[string]string `json:"annotations,omitempty"`

	// Removed arguments: they only exist so that a caller still passing them
	// is told why they are gone (see rejectRemoved) instead of getting an
	// "unknown field" error.
	RemovedToolNames json.RawMessage `json:"toolNames,omitempty"`
	RemovedRuntime   json.RawMessage `json:"runtime,omitempty"`

	WriteOptions
}

type Status struct {
	Name      string `json:"name"`
	Namespace string `json:"namespace"`
	Target
	// Verdict is ready, progressing, failed or unknown.
	Verdict string `json:"verdict"`
	// Summary is one sentence a human or an agent can act on.
	Summary     string             `json:"summary"`
	Template    *TemplateStatus    `json:"template,omitempty"`
	HelmRelease *HelmReleaseStatus `json:"helmRelease,omitempty"`
	Events      []Event            `json:"events,omitempty"`
	// contains filtered or unexported fields
}

type Target struct {
	// Organization owns the cluster: its namespace org-<organization> on the
	// installation holds the Cluster and its kubeconfig Secret.
	Organization string `json:"organization,omitempty"`
	// Cluster is the workload cluster's name.
	Cluster string `json:"cluster,omitempty"`
}

type TemplateStatus struct {
	Exists             bool            `json:"exists"`
	Generation         int64           `json:"generation,omitempty"`
	ObservedGeneration int64           `json:"observedGeneration,omitempty"`
	Harnesses          []HarnessStatus `json:"harnesses"`
}

type ToolBinding struct {
	// Server is the RemoteMCPServer bound (same namespace).
	Server string `json:"server"`
	// Tools narrows the binding to these tools; empty is every tool.
	Tools []string `json:"tools,omitempty"`
}

type Update struct {
	Location
	Name          string  `json:"name"`
	DisplayName   *string `json:"displayName,omitempty"`
	Description   *string `json:"description,omitempty"`
	SystemMessage *string `json:"systemMessage,omitempty"`
	ModelConfig   *string `json:"modelConfig,omitempty"`
	IconURL       *string `json:"iconUrl,omitempty"`
	Skills        *Skills `json:"skills,omitempty"`
	// GitAuthSecretName replaces the skills credential Secret; empty clears it
	// back to the installation's.
	GitAuthSecretName *string            `json:"gitAuthSecretName,omitempty"`
	Toolset           *[]string          `json:"toolset,omitempty"`
	Labels            *map[string]string `json:"labels,omitempty"`
	Annotations       *map[string]string `json:"annotations,omitempty"`
	// RefreshSkills re-resolves every git skill of the agent to the head of
	// its repository's default branch — a skill passed in Skills with a Ref
	// goes to that ref's head — and changes nothing else on the release.
	RefreshSkills bool `json:"refreshSkills,omitempty"`
	// Removed arguments: see Spec.
	RemovedToolNames json.RawMessage `json:"toolNames,omitempty"`
	RemovedRuntime   json.RawMessage `json:"runtime,omitempty"`
	// Force writes to a suspended HelmRelease anyway. A GitOps-owned one is
	// never written live: mode commit changes it in git.
	Force bool `json:"force,omitempty"`

	WriteOptions
}

type UpdateResult struct {
	Agent     Agent          `json:"agent"`
	Before    map[string]any `json:"before"`
	After     map[string]any `json:"after"`
	Changed   []string       `json:"changed"`
	Manifests Manifests      `json:"manifests"`
	// RequestedBy is the authenticated caller the write ran as.
	RequestedBy string `json:"requestedBy,omitempty"`
	WriteOutcome
}

type ValidateResult struct {
	Valid bool `json:"valid"`
	// Mode is create or update.
	Mode string `json:"mode"`
	// Errors lists every schema violation and precondition failure.
	Errors []string `json:"errors,omitempty"`
	// Notes lists the checks the dry run could not make, such as the name
	// check for a caller who may not read the namespace's releases.
	Notes []string `json:"notes,omitempty"`
	// SchemaVersion / SchemaSource say which chart schema judged the values.
	SchemaVersion string    `json:"schemaVersion"`
	SchemaSource  string    `json:"schemaSource"`
	Manifests     Manifests `json:"manifests"`
}

type WriteOptions struct {
	// Mode is apply (default) or commit.
	Mode string `json:"mode,omitempty"`
	// DryRun returns the manifests and, in commit mode, the files and the
	// pull request that would be opened, and writes nothing.
	DryRun bool `json:"dryRun,omitempty"`
	// Repository (owner/name), Branch and Path name the commit target where
	// no Flux Kustomization owns the namespace yet; given, they override the
	// target derived from Flux. Commit mode only.
	Repository string `json:"repository,omitempty"`
	Branch     string `json:"branch,omitempty"`
	Path       string `json:"path,omitempty"`
}

type WriteOutcome struct {
	Mode   string        `json:"mode"`
	DryRun bool          `json:"dryRun"`
	Commit *CommitResult `json:"commit,omitempty"`
}