Documentation
¶
Overview ¶
Package agent detects whether gcx is running inside an AI agent environment (e.g. Claude Code, Cursor, GitHub Copilot, Amazon Q).
Detection happens automatically at init() time by reading well-known environment variables. The result can also be influenced by the --agent CLI flag via SetFlag.
Index ¶
Constants ¶
const ( AnnotationTokenCost = "agent.token_cost" // "small", "medium", "large" AnnotationLLMHint = "agent.llm_hint" // scoping hint for agents AnnotationRequiredScope = "agent.required_scope" // required auth scope AnnotationRequiredRole = "agent.required_role" // required role AnnotationRequiredAction = "agent.required_action" // required action )
Cobra Annotations map keys for agent-facing command metadata.
Variables ¶
var KnownResources = []KnownResource{
resource("Dashboard", "dashboard.grafana.app", "v1beta1", "dashboards", "dashboard", "dash").crud().cost("get", "large").cost("pull", "large").build(),
resource("Folder", "folder.grafana.app", "v1beta1", "folders", "folder").crud().build(),
resource("Playlist", "playlist.grafana.app", "v0alpha1", "playlists").readOnly().build(),
resource("Preferences", "preferences.grafana.app", "v1alpha1", "preferences").readOnly().build(),
resource("ShortURL", "shorturl.grafana.app", "v1beta1", "shorturls").readOnly().build(),
resource("Snapshot", "dashboard.grafana.app", "v0alpha1", "snapshots").readOnly().build(),
resource("AlertRule", "rules.alerting.grafana.app", "v0alpha1", "alertrules").crud().build(),
resource("RecordingRule", "rules.alerting.grafana.app", "v0alpha1", "recordingrules").withOps("get", "push", "pull").build(),
resource("AlertEnrichment", "alertenrichment.grafana.app", "v1beta1", "alert-enrichments").readOnly().build(),
resource("Check", "advisor.grafana.app", "v0alpha1", "checks").readOnly().build(),
resource("CheckType", "advisor.grafana.app", "v0alpha1", "checktypes").readOnly().cost("get", "small").build(),
resource("Repository", "provisioning.grafana.app", "v0alpha1", "repositories").withOps("get", "push").build(),
resource("Job", "provisioning.grafana.app", "v0alpha1", "jobs").readOnly().build(),
resource("Connection", "provisioning.grafana.app", "v0alpha1", "connections").readOnly().cost("get", "small").build(),
resource("Plugin", "plugins.grafana.app", "v0alpha1", "plugins").readOnly().build(),
resource("SecureValue", "secret.grafana.app", "v1beta1", "securevalues").withOps("get", "push").cost("get", "small").build(),
resource("Keeper", "secret.grafana.app", "v1beta1", "keepers").readOnly().cost("get", "small").build(),
resource("Query", "queries.grafana.app", "v1beta1", "queries").readOnly().build(),
resource("SandboxSettings", "sandboxsettings.grafana.app", "v0alpha1", "sandbox-settings").readOnly().cost("get", "small").build(),
resource("AnnouncementBanner", "banners.grafana.app", "v0alpha1", "announcement-banners").withOps("get", "push").cost("get", "small").build(),
}
KnownResources is the static registry of well-known Grafana K8s resource types that are NOT backed by provider adapters. Provider-backed types (SLO, OnCall, Fleet, K6, KG, Incidents, Alert, Synth) are already registered via adapter.AllRegistrations().
This list was verified against a live Grafana 13.0 stack.
Functions ¶
func DetectedFromEnv ¶
func DetectedFromEnv() bool
DetectedFromEnv reports whether agent mode was detected from environment variables, as opposed to being set only via SetFlag.
func IsAgentMode ¶
func IsAgentMode() bool
IsAgentMode reports whether gcx is running in agent mode. The value is determined by environment variables (checked at init time) and the --agent CLI flag (applied via SetFlag).
func ResetForTesting ¶
func ResetForTesting()
ResetForTesting re-runs environment detection from current env vars. Exported for use in tests only.
Types ¶
type CatalogEntry ¶
CatalogEntry represents a catalog resource type for validation comparison.
type KnownResource ¶
type KnownResource struct {
Kind string
Group string
Version string
Aliases []string
Operations map[string]OperationHint // keyed by operation: "get", "push", "pull", "delete"
}
KnownResource describes a well-known Grafana K8s resource type with agent metadata. These types are standard across all Grafana instances and can be annotated statically.
type OperationHint ¶
type OperationHint struct {
TokenCost string // "small", "medium", "large"
LLMHint string // example command for this operation
}
OperationHint describes agent metadata for a single resource operation.
type StaleType ¶
type StaleType struct {
Kind string `json:"kind"`
Group string `json:"group"`
Version string `json:"version"`
Source string `json:"source"` // "well-known" or "adapter"
}
StaleType is a catalog resource type not found on the live instance.
type UncoveredType ¶
type UncoveredType struct {
Kind string `json:"kind"`
Group string `json:"group"`
Version string `json:"version"`
Plural string `json:"plural"`
}
UncoveredType is a live resource type missing from the catalog.
type ValidationResult ¶
type ValidationResult struct {
Uncovered []UncoveredType `json:"uncovered"` // live types not in catalog
Stale []StaleType `json:"stale"` // catalog types not found live
Covered int `json:"covered"` // catalog types confirmed live
Total int `json:"total"` // total live types discovered
}
ValidationResult holds the result of comparing the catalog against live discovery.
func CompareAgainstLive ¶
func CompareAgainstLive(catalog []CatalogEntry, liveDescs resources.Descriptors) *ValidationResult
CompareAgainstLive is the pure comparison logic, separated for testing.
Source Files