agent

package
v0.2.9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 23, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

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

View Source 
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

View Source 
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 AnnotationRegistryPaths added in v0.2.5 

func AnnotationRegistryPaths() []string

AnnotationRegistryPaths returns all command paths in the centralized annotation registry. Used by consistency tests to detect orphaned entries.

func ApplyAnnotations added in v0.2.5 

func ApplyAnnotations(root *cobra.Command)

ApplyAnnotations walks the command tree and applies agent annotations from the centralized registry. Existing annotations on a command are preserved; registry entries only fill in missing keys. Call this after the full command tree is assembled.

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.

func SetFlag 

func SetFlag(enabled bool)

SetFlag is called from the CLI layer after pre-parsing os.Args for the --agent flag. The flag is only set when the user explicitly passes --agent or --agent=false, so it always takes precedence over env detection.

func WalkCommands added in v0.2.5 

func WalkCommands(cmd *cobra.Command, fn func(*cobra.Command))

WalkCommands recursively calls fn on cmd and all its subcommands.

Types

type CatalogEntry 

type CatalogEntry struct {
	Kind    string
	Group   string
	Version string
	Source  string
}

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

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.