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 Agent
	// object 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"`
	// Harness is the Harness that runs the agent (spec.harnessRef.name, else
	// the chart value agent.harness while nothing is rendered).
	Harness string `json:"harness,omitempty"`
	// Skills as pinned: git skills by commit, OCI skills by digest.
	Skills Skills `json:"skills,omitempty"`
	// Plugins as pinned.
	Plugins Plugins `json:"plugins,omitempty"`
	// Egress is the Agent's spec.egress (the chart value agent.egress while
	// nothing is rendered).
	Egress []string `json:"egress,omitempty"`
	// Toolset is the toolset the agent declares: the owning HelmRelease's
	// `toolset` value, or, for a bare Agent object, 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 Agent object's verdict (Ready and the desired revision is
	// the latest successful one); nil while the object is absent or its
	// Harness has not reported.
	Ready *bool `json:"ready"`
	// Status is the Agent object's status, when it exists.
	Status *ObjectStatus `json:"status,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 AgentRef struct {
	Namespace string `json:"namespace"`
	Name      string `json:"name"`
}

type AgentSummary struct {
	Name      string `json:"name"`
	Namespace string `json:"namespace"`
	Target
	Exists             bool     `json:"exists"`
	DisplayName        string   `json:"displayName,omitempty"`
	Description        string   `json:"description,omitempty"`
	ModelConfig        string   `json:"modelConfig,omitempty"`
	Harness            string   `json:"harness,omitempty"`
	Toolset            []string `json:"toolset,omitempty"`
	ImplicitFullAccess bool     `json:"implicitFullAccess,omitempty"`
	Ready              *bool    `json:"ready"`
	Managed            string   `json:"managed"`
	// The owning HelmRelease's state, when it needs attention: suspended,
	// being uninstalled, or not Ready (its reason and message).
	Suspended      bool   `json:"suspended,omitempty"`
	Deleting       bool   `json:"deleting,omitempty"`
	ReleaseReason  string `json:"releaseReason,omitempty"`
	ReleaseMessage string `json:"releaseMessage,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 (2.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 an agent runs on unless it names
	// another: composed as the chart value agent.harness, the Agent object's
	// spec.harnessRef.name.
	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 or git plugin reads them 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 api.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
	// Sessions is the kagent controller the session operations call through
	// agentgateway as the caller. Nil: they are refused as unsupported.
	Sessions SessionClient
}

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"`
	// AgentDeleted: the Agent object was deleted directly (a bare one, or the
	// rendered objects of a suspended release, both with force).
	AgentDeleted           bool `json:"agentDeleted"`
	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 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.
	// Agent is the object a release renders; AgentTemplate is the same group
	// and version (the template is inline in the Agent).
	APIVersions struct {
		Agent           string `json:"agent"`
		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 an agent runs on unless it names another.
	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 ObjectStatus struct {
	// Exists is false while the HelmRelease has not rendered the Agent yet.
	Exists             bool  `json:"exists"`
	Generation         int64 `json:"generation,omitempty"`
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
	// Harness is spec.harnessRef.name, the Harness that runs the agent.
	Harness string `json:"harness,omitempty"`
	// 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 Plugin struct {
	// Path is the bundle's directory within the artifact; empty for the root.
	Path string `json:"path,omitempty"`
	// Git is the git source: URL and Commit (Ref is refused).
	Git *GitSkill `json:"git,omitempty"`
	// OCI is the digest-pinned image reference.
	OCI string `json:"oci,omitempty"`
	// Skills names the bundle's skills to enable; at least one, unique.
	Skills []string `json:"skills"`
}

type Plugins []Plugin

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 SessionClient interface {
	ListSessions(ctx context.Context, token string, agent kagent.Ref, allCreators bool) ([]*apiv1alpha1.Session, error)
	GetSession(ctx context.Context, token, sessionID string) (*apiv1alpha1.Session, error)
	ListSessionTasks(ctx context.Context, token string, agent kagent.Ref, contextID string) ([]*a2apb.Task, error)
	CreateSession(ctx context.Context, token string, agent kagent.Ref, requestID, name string) (*apiv1alpha1.Session, error)
	SendMessage(ctx context.Context, token string, agent kagent.Ref, contextID, messageID, text string) (*a2apb.StreamResponse, error)
}

type SessionDetail struct {
	Session json.RawMessage   `json:"session"`
	Tasks   []json.RawMessage `json:"tasks"`
}

type SessionList struct {
	Agent    AgentRef          `json:"agent"`
	Sessions []json.RawMessage `json:"sessions"`
}

type SessionStart struct {
	Session json.RawMessage `json:"session"`
	Turn    json.RawMessage `json:"turn"`
}

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
	// Agent object's 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 spec.template.description.
	Description string `json:"description,omitempty"`
	// SystemMessage is the system prompt (spec.template.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, the Agent object's spec.harnessRef.name); 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"`
	// Plugins the agent enables skills from; every entry comes pinned.
	Plugins Plugins `json:"plugins,omitempty"`
	// Egress lists the HTTP(S) origins the agent may reach besides what its
	// revision compiles (chart value agent.egress, the Agent's spec.egress),
	// such as https://github.com:443 or https://*.githubusercontent.com.
	Egress []string `json:"egress,omitempty"`
	// GitAuthSecretName names the Secret in the agent's namespace whose key
	// `token` reads the agent's private git skills and plugins (chart value
	// skillsGitAuthSecretRef.name, fanned out to every git source). 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 Agent object 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 StartSession struct {
	Namespace string `json:"namespace,omitempty"`
	Name      string `json:"name"`
	// Message is the first user message of the conversation.
	Message string `json:"message"`
	// RequestID makes a retried start idempotent: the same id answers the
	// session the first attempt created. Empty: a new id per call.
	RequestID string `json:"requestId,omitempty"`
	// SessionName is the conversation's display name; empty leaves it unnamed.
	SessionName string `json:"sessionName,omitempty"`
}

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"`
	Agent       *ObjectStatus      `json:"agent,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 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"`
	Plugins       *Plugins `json:"plugins,omitempty"`
	// Egress replaces the agent's whole egress list; empty clears it.
	Egress *[]string `json:"egress,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"`
}