runtimes

type Authorizations []Grant

type Env struct {
	Available      []string
	Authorizations Authorizations
	Task           string
	Run            string
}

type ErrNoRuntime struct {
	Reason string
	// Offer lists runtimes that are present but unauthorized — the actionable
	// part, because the fix is usually one authorization away.
	Offer []string
}

type Grant struct {
	ID      string `yaml:"id" json:"id"`
	Runtime string `yaml:"runtime" json:"runtime"`
	Scope   Scope  `yaml:"scope" json:"scope"`
	// Task is required for ScopeTask and meaningless otherwise.
	Task string `yaml:"task,omitempty" json:"task,omitempty"`
	// Run is required for ScopeRun.
	Run       string `yaml:"run,omitempty" json:"run,omitempty"`
	GrantedAt string `yaml:"granted_at" json:"granted_at"`
	// Revoked keeps a withdrawn grant on the record rather than deleting it, so
	// "when did this stop being allowed" stays answerable.
	Revoked bool `yaml:"revoked,omitempty" json:"revoked,omitempty"`
}

type Kind string

type Need struct {
	// Model is a pinned catalog model, or "" / "auto" for no constraint.
	Model string
}

type Policy struct {
	Strategy Strategy
	// Allowed is the ordered preference list. Order is meaningful.
	Allowed []string
	// Model is a catalog model id, or "auto".
	Model string
	// Fallback names runtimes that may be tried when the SELECTED runtime fails
	// as a runtime — not when the task fails. See Chain.
	Fallback []string
}

type Resolution struct {
	// What was asked for.
	RequestedStrategy Strategy
	RequestedModel    string
	// What it resolved to.
	Runtime          string
	Model            string
	CredentialSource string
	// Which permission was relied on. Empty for the hosted gateway, which needs
	// none.
	AuthID    string
	AuthScope Scope
	// Chain is the ordered alternates for RUNTIME failure only.
	Chain []string
	// Why explains the choice in one line, for the run record.
	Why string
}

type Runtime struct {
	ID      string
	Display string
	Kind    Kind
	// CredentialSource is the value MEMCODE_CREDENTIAL_SOURCE takes to select
	// this backend, empty for the hosted gateway.
	CredentialSource string
	// Vendor is whose models it serves, for the capability check. Empty means
	// "any" — the hosted gateway serves the whole catalog.
	Vendor string
	// DefaultModel serves a task that asked for `auto`.
	DefaultModel string
	// ZeroMarginalCost is true when a run adds nothing to a bill. This is what
	// "prefer a subscription" actually means, and it is deliberately NOT called
	// "cheapest": cheapest implies a cost comparison across latency, quality,
	// context limits and quota that nobody can make honestly from here.
	ZeroMarginalCost bool
	// Available reports presence on this machine. A pure check — it must never
	// activate anything.
	Available func() bool
}

type Scope string

type Strategy string