guard

Documentation

Index

• Constants
• type Account
• type Assessment
• type Backend
• type Decision
• type Result
  • func (r Result) HasFailures() bool
  • func (r Result) IsFatal() bool
• type Runner
  • func NewRunner(backend Backend) *Runner
  • func (r *Runner) RunOnce(ctx context.Context) (result Result)
• type Summary

Constants

const (
	StateConfirmedExhausted = "confirmed_exhausted"
	StateUnknown            = "unknown"

	DecisionNone    = "none"
	DecisionDisable = "disable"

	OutcomeSkipped   = "skipped"
	OutcomeSuggested = "suggested"
	OutcomeFailed    = "failed"
	// The guard only observes, so nothing can emit these two. They stay declared
	// (and counted in Summary) as reserved values rather than disappearing from
	// the published result shape.
	OutcomeApplied = "applied"
	OutcomeStale   = "stale"

	ReasonConfirmedExhausted = "confirmed_exhausted"
	ReasonAssessmentUnknown  = "assessment_unknown"
	ReasonNotExhausted       = "not_confirmed_exhausted"
	ReasonAlreadyDisabled    = "already_disabled"
	ReasonProbeFailed        = "probe_failed"
	ReasonResetMissing       = "reset_at_missing"
	ReasonUnstableAuthIndex  = "unstable_auth_index"
	ReasonRuntimeOnly        = "runtime_only"
	ReasonMissingAccountID   = "missing_chatgpt_account_id"
	ReasonDisabledUnknown    = "disabled_status_unknown"

	FatalDependencyMissing = "dependency_missing"
	FatalListFailed        = "list_failed"
)

Types

type Account

type Account struct {
	ID               string `json:"id"`
	ChatGPTAccountID string `json:"chatgpt_account_id"`
	AuthIndex        string `json:"auth_index"`
	Name             string `json:"name"`
	Provider         string `json:"provider"`
	Disabled         bool   `json:"disabled"`
	DisabledKnown    bool   `json:"disabled_known"`
	Unavailable      bool   `json:"unavailable"`
	RuntimeOnly      bool   `json:"runtime_only"`
	UpdatedAt        string `json:"updated_at"`
}

Account is the guard's intentionally small view of an upstream account. Adapters in other packages translate their API models into this type.

type Assessment

type Assessment struct {
	State       string     `json:"state"`
	Reason      string     `json:"reason"`
	ResetAt     *time.Time `json:"reset_at"`
	UsedPercent *float64   `json:"used_percent"`
}

type Backend

type Backend interface {
	List(context.Context) ([]Account, error)
	ProbeCodex(context.Context, Account) (Assessment, error)
}

type Decision

type Decision struct {
	Identity    string   `json:"identity"`
	Name        string   `json:"name,omitempty"`
	AuthIndex   string   `json:"auth_index,omitempty"`
	Provider    string   `json:"provider,omitempty"`
	State       string   `json:"state,omitempty"`
	Decision    string   `json:"decision"`
	Outcome     string   `json:"outcome"`
	Reason      string   `json:"reason"`
	ResetAt     string   `json:"reset_at,omitempty"`
	UsedPercent *float64 `json:"used_percent,omitempty"`
}

type Result

type Result struct {
	OK             bool       `json:"ok"`
	PartialFailure bool       `json:"partial_failure"`
	Fatal          bool       `json:"fatal"`
	FatalError     string     `json:"fatal_error,omitempty"`
	Decisions      []Decision `json:"decisions"`
	Summary        Summary    `json:"summary"`
}

func (Result) HasFailures

func (r Result) HasFailures() bool

func (Result) IsFatal

func (r Result) IsFatal() bool

type Runner

type Runner struct {
	Backend Backend
}

func NewRunner

func NewRunner(backend Backend) *Runner

func (*Runner) RunOnce

func (r *Runner) RunOnce(ctx context.Context) (result Result)

RunOnce evaluates every Codex account once and reports what it would suggest. It never changes account state: acting on a suggestion is a separate, explicitly authorized `auth-file set-status` call.

type Summary

type Summary struct {
	Total     int `json:"total"`
	Suggested int `json:"suggested"`
	Applied   int `json:"applied"`
	Skipped   int `json:"skipped"`
	Failed    int `json:"failed"`
	Stale     int `json:"stale"`
}

Summary counts decisions by outcome. `Applied` and `Stale` are reserved and always zero — see the outcome constants above.