Documentation
¶
Index ¶
- Constants
- func DefaultAgentRoles() []string
- func DefaultAllowedRemoteResources() []string
- func EffectiveYAML(r PerRepoConfigReader) ([]byte, error)
- func EnsureDefaultAllowedRemoteResources(existing []string) []string
- func FormatSafetyRelaxations(rs []SafetyRelaxation) string
- func GatewayPathPrefix(p string) (string, error)
- func IsAgentExplicitlyDisabled(agents []AgentEntry, name string) bool
- func IsPerRepoYAML(data []byte) bool
- func ManagedConfigSchema() reflect.Type
- func PerRepoDefaultRoles() []string
- func ReservedSubagentKeys() []string
- func SafetyRelaxationKeys(rs []SafetyRelaxation) []string
- func ValidAgentNames() []string
- func ValidAuthorizationProviders() []string
- func ValidConfigAgentName(name string) bool
- func ValidEffort(level string) bool
- func ValidEffortLevels() []string
- func ValidGatewayAPIs() []string
- func ValidGatewayAuthModes() []string
- func ValidModelAliasKeys() []string
- func ValidModelRef(ref string) bool
- func ValidProviders() []string
- func ValidRoles() []string
- func ValidRuntimes() []string
- func ValidSubagentKey(key string) bool
- func ValidateAgentEntries(agents []AgentEntry, allowlist []string) error
- func ValidateGatewayCompat(compat map[string]any, api string) error
- func ValidateGatewayModelID(id string) error
- func ValidateGatewayModelsFilePath(p string) error
- func ValidateGatewayURL(raw string) error
- func ValidateManagedLayer(w PerRepoConfigWriter) error
- func ValidateMergedManaged(w PerRepoConfigWriter) error
- func ValidateModelAliases(aliases map[string]string) error
- type AgentEntry
- type AgentLister
- type AllowTargets
- type AllowedResourcesReader
- type AuthorizationProvider
- type CommentNotificationConfig
- type ConfigReader
- type ConfigWriter
- type CreateIssuesConfig
- type CreateIssuesReader
- type DeclaredInfrastructure
- type GatewayURL
- type InferenceGatewayConfig
- func (c InferenceGatewayConfig) EffectiveAuth() string
- func (c InferenceGatewayConfig) HasModelList() bool
- func (c InferenceGatewayConfig) IsAPIKey() bool
- func (c InferenceGatewayConfig) IsZero() bool
- func (c InferenceGatewayConfig) Missing() []string
- func (c InferenceGatewayConfig) ModelIDs() []string
- func (c InferenceGatewayConfig) Trimmed() InferenceGatewayConfig
- func (c InferenceGatewayConfig) Validate() error
- type InferenceGatewayModel
- type KillSwitchReader
- type LoadOpts
- type ManagedConfig
- func (o ManagedConfig) Clone() ManagedConfig
- func (o ManagedConfig) ExplicitAllowedRemoteResources() ([]string, bool)
- func (o ManagedConfig) ExplicitRoles() ([]string, bool)
- func (o ManagedConfig) ExplicitRuntime() string
- func (o ManagedConfig) IsSet() bool
- func (o ManagedConfig) IsZero() bool
- func (o ManagedConfig) MarshalYAML() (interface{}, error)
- func (o *ManagedConfig) UnmarshalYAML(value *yaml.Node) error
- func (o ManagedConfig) WithCreateIssuesRepos(repos []string) ManagedConfig
- func (o ManagedConfig) Writer() PerRepoConfigWriter
- type ModelsConfig
- type OpenAIWIFConfig
- type PerRepoConfigReader
- type PerRepoConfigWriter
- func LayerOnBase(overlay PerRepoConfigWriter, baseYAML []byte) (PerRepoConfigWriter, error)
- func MergeManaged(parent, child PerRepoConfigWriter) PerRepoConfigWriter
- func NewEmptyPerRepoOverlay() PerRepoConfigWriter
- func NewPerRepoConfig(roles []string, targetRepo string) PerRepoConfigWriter
- func ParsePerRepoConfigWriter(data []byte) (PerRepoConfigWriter, error)
- func ParsePerRepoConfigWriterLayered(overlayData []byte, baseData []byte) (PerRepoConfigWriter, error)
- type PerRepoInferenceConfig
- type ReactionNotificationConfig
- type SafetyRelaxation
- func CheckManagedSafetyGate(current PerRepoConfigReader, candidate PerRepoConfigWriter) []SafetyRelaxation
- func CheckManagedSafetyGateFromLayerPairs(currentYAML, currentBaseYAML []byte, candidate PerRepoConfigWriter, ...) ([]SafetyRelaxation, error)
- func CheckManagedSafetyGateFromLayers(currentYAML []byte, candidate PerRepoConfigWriter, baseYAML []byte) ([]SafetyRelaxation, error)
- type StatusNotificationConfig
- type StatusNotificationsReader
Constants ¶
const ( // DefaultUpstreamRepo is the canonical fullsend repository for layered workflow calls. DefaultUpstreamRepo = "fullsend-ai/fullsend" // DefaultUpstreamRef is the default ref for layered upstream workflow calls. DefaultUpstreamRef = "main" // DefaultGHRunner is the default GitHub Actions runner image for scaffold workflows. DefaultGHRunner = "ubuntu-24.04" // DefaultSandboxImage and DefaultCodeImage are the sandbox images // `fullsend agent new` writes into a generated harness. They track the // fleet's pins in fullsend-ai/agents (harness/triage.yaml and // harness/code.yaml). Nothing updates them automatically: repin them by // hand when a release repins the fleet. `agent new --image` overrides // them. DefaultSandboxImage = "ghcr.io/fullsend-ai/fullsend-sandbox@sha256:bcf8cd84a37623d761d38f2a6f51d20283f8798b7d3eeb9c509a2503c074bd55" DefaultCodeImage = "ghcr.io/fullsend-ai/fullsend-code@sha256:3055d4f52136a7c89fb8aa1976b468a5f9dd929c6be55fd6cd958e222c6e18ca" )
const ( // DefaultPerRepoMintURL is the hosted public mint used when no // mint_url is configured in config.yaml or config.base.yaml. DefaultPerRepoMintURL = "https://mint.fullsend.sh" // DefaultPerRepoInferenceProvider is the default inference backend. DefaultPerRepoInferenceProvider = "vertex" // DefaultPerRepoInferenceRegion is the default GCP region for // inference requests. DefaultPerRepoInferenceRegion = "global" )
Operational code defaults for per-repo configs. These are the terminal values in the overlay → base → code defaults chain (ADR 0069 Decision 2). Callers that need the canonical default value without constructing a full config can reference these constants directly.
const ( GatewayAPIOpenAIResponses = "openai-responses" GatewayAPIAnthropicMessages = "anthropic-messages" GatewayAPIOpenAICompletions = "openai-completions" )
Inference gateway APIs a model may speak (ADR 0137). They match the pi-inference-gateway extension's per-model "api" values.
const ( // GatewayAuthOIDC presents the job's forge OIDC assertion for the // block's audience (ADR 0137). It is the default and the recommended // mode: the forge stores no reusable key. GatewayAuthOIDC = "oidc" // GatewayAuthAPIKey presents a gateway API key the runner reads from // FULLSEND_INFERENCE_GATEWAY_API_KEY (a forge secret or the local // environment). It is supported for gateways that cannot trust forge // OIDC, but it relies on a long-lived secret: use it with caution and // prefer oidc when the gateway supports it. GatewayAuthAPIKey = "api-key" )
Inference gateway credential modes (inference.gateway.auth). There is no implicit precedence and no fallback between them: the block names one.
const ( OverlayConfigFile = "config.yaml" BaseConfigFile = "config.base.yaml" )
Layer file names of a per-repo config directory (ADR 0069).
const GatewayAPIBasePath = "/v1"
GatewayAPIBasePath is the model API base path the runner adds under the gateway URL: the runtimes call <url>/v1/..., and the egress profile binds the credential to <prefix>/v1/** only.
const MaxGatewayModelIDLength = 256
MaxGatewayModelIDLength is the longest model id the pi-inference-gateway extension accepts (v0.1.1 src/config.ts MAX_MODEL_ID_LENGTH), counted in UTF-16 code units as JavaScript counts string length.
Variables ¶
This section is empty.
Functions ¶
func DefaultAgentRoles ¶
func DefaultAgentRoles() []string
DefaultAgentRoles returns the standard set of agent roles installed when no custom roles are specified. The fix stage reuses the coder app (role: coder) so it does not need a separate app or PEM.
func DefaultAllowedRemoteResources ¶ added in v0.24.0
func DefaultAllowedRemoteResources() []string
DefaultAllowedRemoteResources returns the standard allowlist prefixes for base composition and agent registration URLs.
func EffectiveYAML ¶ added in v0.47.0
func EffectiveYAML(r PerRepoConfigReader) ([]byte, error)
EffectiveYAML renders the effective values of a layered per-repo configuration (overlay → base → code defaults) as a YAML mapping, one top-level key per setting, resolved through the whole parent chain. It is a read-only view for operator guidance (for example the effective difference shown when adopting an existing configuration file); it is not a loadable configuration file.
func EnsureDefaultAllowedRemoteResources ¶ added in v0.31.0
EnsureDefaultAllowedRemoteResources returns a new slice with default allowed-remote-resources prefixes merged into the provided list. Nil input (field omitted from YAML) returns defaults alone. An explicit empty slice (allowed_remote_resources: []) is returned unchanged to preserve deny-all semantics. Non-empty input gets any missing defaults appended (preserving the caller's original ordering).
func FormatSafetyRelaxations ¶ added in v0.44.0
func FormatSafetyRelaxations(rs []SafetyRelaxation) string
FormatSafetyRelaxations joins relaxations for error and status output.
func GatewayPathPrefix ¶ added in v0.47.1
GatewayPathPrefix checks the escaped path of a gateway URL and returns its prefix: "" for an empty path or "/", otherwise the path without a trailing slash. The prefix must be a clean absolute path: no empty (doubled-slash), "." or ".." segment, no percent-encoding (so no encoded "/"), only RFC 3986 unreserved characters in each segment, and no trailing /v1, which the runner adds itself.
func IsAgentExplicitlyDisabled ¶ added in v0.33.0
func IsAgentExplicitlyDisabled(agents []AgentEntry, name string) bool
IsAgentExplicitlyDisabled returns true if the last config entry matching name has Enabled explicitly set to false. Iterates in reverse to respect last-writer-wins ordering.
func IsPerRepoYAML ¶ added in v0.31.0
IsPerRepoYAML reports whether raw YAML parses and is free of the top-level keys of the removed per-org configuration format (dispatch, repos, defaults). A per-repo config never has those keys, while a per-org config always did, so their presence identifies a leftover per-org file that must be rejected rather than loaded.
func ManagedConfigSchema ¶ added in v0.48.0
ManagedConfigSchema returns the struct type whose yaml tags define the fields a managed configuration block accepts. Manifest editors walk it to resolve config paths without keeping a separate list of keys.
func PerRepoDefaultRoles ¶ added in v0.8.0
func PerRepoDefaultRoles() []string
PerRepoDefaultRoles returns agent roles for per-repo installation. The "fullsend" dispatch role is excluded because per-repo mode uses the target repo's shim workflow for dispatch instead of a separate app.
func ReservedSubagentKeys ¶ added in v0.42.0
func ReservedSubagentKeys() []string
ReservedSubagentKeys returns the persona names reserved by the runtime (in addition to the run's own agent name and ValidAgentNames).
func SafetyRelaxationKeys ¶ added in v0.44.0
func SafetyRelaxationKeys(rs []SafetyRelaxation) []string
SafetyRelaxationKeys returns the affected configuration keys in order.
func ValidAgentNames ¶ added in v0.38.0
func ValidAgentNames() []string
ValidAgentNames returns the built-in agents fullsend dispatches by name — the names an agents: entry may tune without a source. These are the names passed to `fullsend run <agent>` and used by workflow stages. They are NOT harness role: values — "code" and "fix" both carry role: coder.
func ValidAuthorizationProviders ¶ added in v0.44.0
func ValidAuthorizationProviders() []string
ValidAuthorizationProviders returns the set of recognized authorization provider names.
func ValidConfigAgentName ¶ added in v0.44.0
ValidConfigAgentName reports whether name is acceptable as an agents: entry name. Exported so a caller that generates an agent can apply the same rule before writing anything, rather than discovering the mismatch when registration fails after the files are already on disk.
func ValidEffort ¶ added in v0.38.0
ValidEffort reports whether level is an accepted effort value.
func ValidEffortLevels ¶ added in v0.38.0
func ValidEffortLevels() []string
ValidEffortLevels returns the accepted effort values, in documentation order.
func ValidGatewayAPIs ¶ added in v0.47.0
func ValidGatewayAPIs() []string
ValidGatewayAPIs returns the accepted per-model "api" values for an inference.gateway model list.
func ValidGatewayAuthModes ¶ added in v0.47.0
func ValidGatewayAuthModes() []string
ValidGatewayAuthModes returns the accepted inference.gateway.auth values.
func ValidModelAliasKeys ¶ added in v0.42.0
func ValidModelAliasKeys() []string
ValidModelAliasKeys returns the accepted alias keys for models.aliases.
func ValidModelRef ¶ added in v0.38.0
ValidModelRef reports whether ref is a well-formed model reference (single segment or provider/id form). Exported for use by harness validation and per-run override validation.
func ValidProviders ¶ added in v0.0.3
func ValidProviders() []string
ValidProviders returns the set of recognized inference providers.
func ValidRoles ¶
func ValidRoles() []string
ValidRoles returns the set of agent roles accepted in `.fullsend` `roles:` config. This is intentionally narrower than mintcore's canonical roles: mint-only dogfood roles (e.g. scribe) can be registered with `fullsend mint add-role` before scaffold/workflow wiring lands, and must not silently pass config validation.
func ValidRuntimes ¶ added in v0.30.0
func ValidRuntimes() []string
ValidRuntimes returns the set of recognized agent runtimes. "pi" (#6464), "codex" (#6920), and "opencode" (#6035, unbound-force#510) are opt-in per repo, per agent, or as a repos.yaml default; "dummy" and "dummy-playback" are for behaviour tests only.
NOTE: opencode does not yet provide sandbox hooks for write-capable agents (code, fix). The exit-97 guard is keyed on security.enabled, not agent role: with security enabled it requires the adapter, while disabling security does not block write-capable roles. Role-aware enforcement is deferred to unbound-force#515 with the hook adapter.
func ValidSubagentKey ¶ added in v0.42.0
ValidSubagentKey reports whether key is a well-formed sub-agent persona name: lowercase alphanumeric segments joined by hyphens, or "default". Maximum 64 characters.
func ValidateAgentEntries ¶ added in v0.25.0
func ValidateAgentEntries(agents []AgentEntry, allowlist []string) error
ValidateAgentEntries validates a complete, self-contained agent list — a per-repo config with its full parent chain resolved — enforcing both the allowlist check and the compiled-in-name requirement. See validateAgentEntries for the relaxed checks used during repos.yaml config overlay validation (ADR 0122).
func ValidateGatewayCompat ¶ added in v0.47.0
ValidateGatewayCompat checks a model's compat map the way extension v0.1.1 reads it (src/config.ts and validateCompat in src/compat.ts), but refuses what the extension would drop with a warning:
- flag names match COMPAT_KEY_RE;
- a flag the model's api declares must have that transport's type (with api empty, the type of any transport that declares it); structured fields such as allowedFallbackModels are refused;
- any other value is a boolean, a string or a finite number, under a name that does not look like a credential or header.
Holding values to these scalar types also keeps nested data (including the map[interface{}]interface{} yaml.v3 builds for a non-string-keyed mapping) out of the rendered file, and makes the one-level copy in cloneGatewayModels a full copy. Free-text string values cannot be scanned for secrets; the name filter and the typed known flags narrow where one could go.
func ValidateGatewayModelID ¶ added in v0.47.0
ValidateGatewayModelID applies the extension's model-id rule (v0.1.1 src/config.ts isValidModelId): 1-256 characters, no whitespace and no control characters. The extension skips any other id with a warning, so a run would otherwise fail later with "model not found".
func ValidateGatewayModelsFilePath ¶ added in v0.47.0
ValidateGatewayModelsFilePath checks that p is a clean, relative repository path that stays inside the repository.
func ValidateGatewayURL ¶ added in v0.47.0
ValidateGatewayURL checks that raw is a usable gateway URL (ParseGatewayURL).
func ValidateManagedLayer ¶ added in v0.44.0
func ValidateManagedLayer(w PerRepoConfigWriter) error
ValidateManagedLayer validates a single repos.yaml managed-configuration layer (defaults.config, github.config, gitlab.config, or one repository's config block, ADR 0122) in isolation, before the layers are merged. It runs the same locally-set field checks as Validate, plus structural checks on this layer's own agent entries (name format, duplicate names, URL scheme and integrity hash) — but it does not check a URL agent against an allowlist (another layer may supply the allowed_remote_resources prefix) and does not require an override-only entry (no source) to name a compiled-in agent (it may tune a custom agent registered in config.base.yaml, which this layer cannot see). Those two checks run in ValidateMergedManaged once the layers are merged.
func ValidateMergedManaged ¶ added in v0.44.0
func ValidateMergedManaged(w PerRepoConfigWriter) error
ValidateMergedManaged validates a repos.yaml managed configuration (ADR 0122) after defaults.config, the platform config, and the repository config have been merged (mergeManagedConfig). The resolved allowlist is now correct, so a URL-sourced agent entry is checked against it; an override-only entry is still not required to name a compiled-in agent, since config.base.yaml — which may register the agent it tunes — is not layered on until the managed file is written and later read through LayeredConfig.
func ValidateModelAliases ¶ added in v0.42.0
ValidateModelAliases checks a models.aliases map: every key is one of ValidModelAliasKeys, every value is a ValidModelRef, and no value is itself an alias key — the runtimes consult the alias table once, so `sonnet: opus` would reach the provider as the literal id "opus". Exported because the run path validates the effective (merged) map (nothing writes the block through the CLI, so Validate on the write paths alone would never see a hand-edited file).
Types ¶
type AgentEntry ¶
type AgentEntry struct {
Name string `yaml:"name,omitempty"`
Source string `yaml:"source,omitempty"`
Ref string `yaml:"ref,omitempty"`
Enabled *bool `yaml:"enabled,omitempty"`
Runtime string `yaml:"runtime,omitempty"`
Model string `yaml:"model,omitempty"`
Effort string `yaml:"effort,omitempty"`
Subagents map[string]*string `yaml:"subagents,omitempty"`
}
AgentEntry represents a registered agent source in config. It supports both string shorthand (just the source URL/path) and object form (with an explicit name override).
Enabled controls whether the agent participates in the merged agent set. When nil (omitted) the agent defaults to enabled. When explicitly set to false the agent is suppressed — this allows disabling built-in scaffold agents without removing their role. A suppression-only entry (Enabled=false, no Source) is valid.
Ref records the original branch or tag ref that was resolved to a commit SHA when the agent was adopted via `agent add`. When present, `agent update` re-resolves against this ref instead of the repo's default branch, so agents adopted from non-default branches stay on their intended branch across updates. Empty for entries that predate this field or were adopted with an explicit commit SHA.
Runtime, Model and Effort tune how the agent runs (ADR 0091): they override the repo-wide runtime: key and the harness model:/effort: for this agent, beneath the per-run --runtime/--model/--effort flags and FULLSEND_* variables. An enabled entry may carry them without a Source — an override-only entry — when Name is a built-in agent (ValidAgentNames) or matches a sourced entry in a parent layer; the built-in keeps resolving through the agents-repo fallback.
Subagents maps persona names to model references, controlling which model each sub-agent persona runs on. The "default" key sets the fallback for personas without an explicit entry. A nil *string value tombstones an inherited entry (per-key layered merge, like ConfigModelAliases). Values are ValidModelRef through the repo alias table. Keys must match ValidSubagentKey.
func AgentSettingsFor ¶ added in v0.38.0
func AgentSettingsFor(agents []AgentEntry, name string) (AgentEntry, bool)
AgentSettingsFor returns the entry for name (case-insensitive) from an effective (merged) agent list, and whether one exists. Callers read Runtime/Model/Effort from it.
func UpsertAgentSettings ¶ added in v0.38.0
func UpsertAgentSettings(agents []AgentEntry, name, runtime, model, effort string, subagents map[string]*string) []AgentEntry
UpsertAgentSettings sets runtime/model/effort/subagents for name on a layer's local agent list: on the entry with that name when present, else as a new override-only entry. An empty value clears that setting. Returns the updated list.
func (AgentEntry) DerivedName ¶ added in v0.24.0
func (a AgentEntry) DerivedName() string
DerivedName returns the explicit Name if set, otherwise derives one from the Source filename (e.g. "triage.yaml" → "triage").
func (AgentEntry) HasSettings ¶ added in v0.38.0
func (a AgentEntry) HasSettings() bool
HasSettings reports whether the entry tunes runtime, model, effort or subagents.
func (AgentEntry) IsEnabled ¶ added in v0.33.0
func (a AgentEntry) IsEnabled() bool
IsEnabled returns whether the agent entry is enabled. A nil Enabled pointer (field omitted) defaults to true.
func (AgentEntry) IsOverrideOnly ¶ added in v0.38.0
func (a AgentEntry) IsOverrideOnly() bool
IsOverrideOnly reports whether the entry only tunes an agent defined elsewhere: enabled, no source, at least one setting.
func (*AgentEntry) UnmarshalYAML ¶ added in v0.24.0
func (a *AgentEntry) UnmarshalYAML(value *yaml.Node) error
UnmarshalYAML implements yaml.Unmarshaler so that a plain string is treated as a source-only entry, while a mapping decodes normally. Old-format entries (role/name/slug identity tuples from pre-ADR-0058 config) are detected and rejected with a clear error message.
type AgentLister ¶ added in v0.31.0
type AgentLister interface {
AgentEntries() []AgentEntry
}
AgentLister provides read access to registered agent entries.
type AllowTargets ¶ added in v0.18.0
type AllowTargets struct {
Orgs []string `yaml:"orgs,omitempty"`
Repos []string `yaml:"repos,omitempty"`
}
AllowTargets defines which orgs and repos agents may create issues in.
type AllowedResourcesReader ¶ added in v0.31.0
type AllowedResourcesReader interface {
AllowedResources() []string
}
AllowedResourcesReader provides read access to the allowed remote resources list.
type AuthorizationProvider ¶ added in v0.44.0
type AuthorizationProvider struct {
Provider string `yaml:"provider"`
}
AuthorizationProvider identifies an opt-in authorization backend that supplements the default collaborator-API permission check.
type CommentNotificationConfig ¶ added in v0.15.0
type CommentNotificationConfig struct {
Start string `yaml:"start,omitempty"`
Completion string `yaml:"completion,omitempty"`
}
CommentNotificationConfig controls start/completion comments. Valid start values: "enabled" (default), "disabled". Valid completion values: "enabled" (default), "on_failure", "disabled".
type ConfigReader ¶ added in v0.31.0
type ConfigReader interface {
AgentLister
KillSwitchReader
AllowedResourcesReader
CreateIssuesReader
StatusNotificationsReader
ConfigVersion() string
}
ConfigReader is the common read interface for the general-purpose configuration fields. Consumer packages should depend on this interface rather than accessing struct fields directly.
func LoadConfig ¶ added in v0.31.0
func LoadConfig(dir string, opts LoadOpts) (ConfigReader, error)
LoadConfig reads config.yaml (and config.base.yaml if present) from dir, returning a ConfigReader. The parent chain is wired as overlay (config.yaml) → base (config.base.yaml) → code defaults. A config.yaml in the removed per-org format is rejected. This is the preferred entry point for consumer packages that only need read access.
type ConfigWriter ¶ added in v0.31.0
type ConfigWriter interface {
ConfigReader
SetKillSwitch(bool)
SetAgents([]AgentEntry)
SetAllowedRemoteResources([]string)
SetStatusNotifications(*StatusNotificationConfig)
Marshal() ([]byte, error)
Validate() error
}
ConfigWriter extends ConfigReader with mutation methods for the general-purpose configuration fields.
func LoadConfigWriter ¶ added in v0.32.0
func LoadConfigWriter(dir string, opts LoadOpts) (ConfigWriter, error)
LoadConfigWriter reads config.yaml (and config.base.yaml if present) from dir, returning a ConfigWriter. The parent chain is wired as overlay (config.yaml) → base (config.base.yaml) → code defaults, and a config.yaml in the removed per-org format is rejected. Only the overlay layer is mutable; base and defaults are read-only via the parent pointer. This is the preferred entry point for consumer packages that need read-write access (e.g. CLI commands that modify and write-back config).
type CreateIssuesConfig ¶ added in v0.18.0
type CreateIssuesConfig struct {
AllowTargets AllowTargets `yaml:"allow_targets"`
}
CreateIssuesConfig controls cross-repo issue creation by agents.
type CreateIssuesReader ¶ added in v0.31.0
type CreateIssuesReader interface {
IssueCreationConfig() *CreateIssuesConfig
}
CreateIssuesReader provides read access to cross-repo issue creation configuration.
type DeclaredInfrastructure ¶ added in v0.48.0
type DeclaredInfrastructure struct {
MintURL string
InferenceProject string
InferenceRegion string
InferenceWIFProvider string
}
DeclaredInfrastructure holds the installation infrastructure values that a managed overlay or a config.base.yaml preset explicitly declares. Unlike the layered accessors it never falls back to code defaults: an empty field means no layer declares the value.
func DeclaredInfrastructureValues ¶ added in v0.48.0
func DeclaredInfrastructureValues(overlay PerRepoConfigWriter, baseYAML []byte) (DeclaredInfrastructure, error)
DeclaredInfrastructureValues returns the mint URL and Vertex inference values declared by overlay (which wins) or by baseYAML. baseYAML may be empty. Code defaults are deliberately not consulted, so callers can tell a declared value from an inherited default.
type GatewayURL ¶ added in v0.47.1
type GatewayURL struct {
// Origin is scheme://host[:port], with no trailing slash.
Origin string
// Hostname is the host without a port, as written.
Hostname string
// Prefix is the optional path prefix the gateway serves its API
// under: "" for a bare origin, otherwise a clean absolute path with no
// trailing slash, for example "/team-a".
Prefix string
}
GatewayURL is a validated inference.gateway.url split into the parts the runner builds on (ParseGatewayURL).
func ParseGatewayURL ¶ added in v0.47.1
func ParseGatewayURL(raw string) (GatewayURL, error)
ParseGatewayURL checks that raw is the gateway's URL and splits it: an absolute https URL with a host, an optional path prefix (GatewayPathPrefix), no port other than 443, and no embedded credentials, query or fragment. The runner appends the /v1/... model API paths itself, and the OpenShell egress profile binds the host on port 443 only. Plain http, and any port, is accepted only for a loopback host (test servers), as actionsoidc.RequireSecureURL does.
func (GatewayURL) BaseURL ¶ added in v0.47.1
func (g GatewayURL) BaseURL() string
BaseURL returns Origin followed by Prefix: the URL the runtimes add GatewayAPIBasePath and the model API paths to.
type InferenceGatewayConfig ¶ added in v0.47.0
type InferenceGatewayConfig struct {
URL string `yaml:"url,omitempty"`
Audience string `yaml:"audience,omitempty"`
Auth string `yaml:"auth,omitempty"`
Models map[string]InferenceGatewayModel `yaml:"models,omitempty"`
ModelsFile string `yaml:"models_file,omitempty"`
}
InferenceGatewayConfig is the inference.gateway block (ADR 0137): a self-hosted, OpenAI/Anthropic-compatible gateway. Auth selects the credential mode (EffectiveAuth): oidc (the default) presents the job's forge OIDC token and requires Audience; api-key presents a gateway API key and needs no audience. URL is always required (see Missing). The model list is optional at block level and takes exactly one of two forms: Models (inline) or ModelsFile (a repository path to a file in the pi-inference-gateway extension's own config format). A runtime that cannot discover models (pi under PI_OFFLINE) requires one when a gateway/ model is resolved.
There is deliberately no runner-variable override: the committed config is the single source, and pull-request events read it from the base branch, so a pull request cannot redirect its own run.
func (InferenceGatewayConfig) EffectiveAuth ¶ added in v0.47.0
func (c InferenceGatewayConfig) EffectiveAuth() string
EffectiveAuth returns the block's credential mode: Auth, or GatewayAuthOIDC when it is unset.
func (InferenceGatewayConfig) HasModelList ¶ added in v0.47.0
func (c InferenceGatewayConfig) HasModelList() bool
HasModelList reports whether either model-list form is set.
func (InferenceGatewayConfig) IsAPIKey ¶ added in v0.47.0
func (c InferenceGatewayConfig) IsAPIKey() bool
IsAPIKey reports whether the block uses the api-key credential mode.
func (InferenceGatewayConfig) IsZero ¶ added in v0.47.0
func (c InferenceGatewayConfig) IsZero() bool
IsZero reports whether no field is set.
func (InferenceGatewayConfig) Missing ¶ added in v0.47.0
func (c InferenceGatewayConfig) Missing() []string
Missing lists the required fields still unset, in a fixed order, so a partial block can be reported precisely: url always, and audience in the oidc mode (the api-key mode requests no OIDC assertion). The model list is not required at block level: it is checked when a runtime that needs it resolves a gateway/ model.
func (InferenceGatewayConfig) ModelIDs ¶ added in v0.47.0
func (c InferenceGatewayConfig) ModelIDs() []string
ModelIDs returns the inline model ids in sorted order.
func (InferenceGatewayConfig) Trimmed ¶ added in v0.47.0
func (c InferenceGatewayConfig) Trimmed() InferenceGatewayConfig
Trimmed returns the block with surrounding whitespace removed from the scalar fields, so a whitespace-only YAML value counts as unset. Models is copied (shallowly per entry) so the result does not alias the receiver's map.
func (InferenceGatewayConfig) Validate ¶ added in v0.47.0
func (c InferenceGatewayConfig) Validate() error
Validate checks the block's set fields. It does not enforce all-or-none on url + audience, because the block layers field by field (an org preset may carry url and audience while a repository adds its models); callers that resolved the effective block check Missing.
type InferenceGatewayModel ¶ added in v0.47.0
type InferenceGatewayModel struct {
API string `yaml:"api"`
Compat map[string]any `yaml:"compat,omitempty"`
ContextWindow int `yaml:"contextWindow,omitempty"`
MaxTokens int `yaml:"maxTokens,omitempty"`
}
InferenceGatewayModel holds the per-model settings of an inline inference.gateway model list. Field names follow the pi-inference-gateway extension's config keys so they render verbatim.
type KillSwitchReader ¶ added in v0.31.0
type KillSwitchReader interface {
IsKillSwitchActive() bool
}
KillSwitchReader provides read access to the kill switch state.
type LoadOpts ¶ added in v0.31.0
type LoadOpts struct {
// MissingOK returns a default config when config.yaml is absent.
MissingOK bool
}
LoadOpts controls how LoadConfig handles a missing config.yaml.
type ManagedConfig ¶ added in v0.44.0
type ManagedConfig struct {
// contains filtered or unexported fields
}
ManagedConfig is a sparse per-repo managed configuration as declared in repos.yaml defaults.config, github.config, gitlab.config, and per-repository config blocks (ADR 0122). Every per-repo .fullsend/config.yaml field is accepted. The zero value means the key was omitted.
func (ManagedConfig) Clone ¶ added in v0.47.1
func (o ManagedConfig) Clone() ManagedConfig
Clone returns a deep copy of o that shares no mutable state with it: the Writer of the copy can be mutated without affecting the receiver. An unset configuration stays unset.
func (ManagedConfig) ExplicitAllowedRemoteResources ¶ added in v0.47.1
func (o ManagedConfig) ExplicitAllowedRemoteResources() ([]string, bool)
ExplicitAllowedRemoteResources returns the allowed_remote_resources list declared by this layer and whether the layer declares the key at all. An explicit empty list reports (empty, true). Unlike the layered AllowedResources accessor it does not union with or fall back to code defaults.
func (ManagedConfig) ExplicitRoles ¶ added in v0.47.0
func (o ManagedConfig) ExplicitRoles() ([]string, bool)
ExplicitRoles returns the roles declared by this layer and whether the layer declares roles at all. Unlike the layered ConfigRoles accessor it does not fall back to code defaults, so an explicit value that equals a default is still reported as declared.
func (ManagedConfig) ExplicitRuntime ¶ added in v0.47.1
func (o ManagedConfig) ExplicitRuntime() string
ExplicitRuntime returns the runtime declared by this layer, or "" when the layer is unset or omits runtime. Unlike the layered ConfigRuntime accessor it does not fall back to code defaults.
func (ManagedConfig) IsSet ¶ added in v0.44.0
func (o ManagedConfig) IsSet() bool
IsSet reports whether a config mapping was present in YAML, including an empty mapping (`config: {}`) that opts a repository into managed configuration without supplying values.
func (ManagedConfig) IsZero ¶ added in v0.44.0
func (o ManagedConfig) IsZero() bool
IsZero reports whether the managed configuration was omitted. yaml.v3 uses this for omitempty so unset blocks are not marshaled as null.
func (ManagedConfig) MarshalYAML ¶ added in v0.44.0
func (o ManagedConfig) MarshalYAML() (interface{}, error)
MarshalYAML encodes the managed configuration as a sparse mapping without the config.yaml file header.
func (*ManagedConfig) UnmarshalYAML ¶ added in v0.44.0
func (o *ManagedConfig) UnmarshalYAML(value *yaml.Node) error
UnmarshalYAML strictly decodes a mapping into a sparse per-repo managed configuration. Unknown fields are rejected with field-specific errors.
func (ManagedConfig) WithCreateIssuesRepos ¶ added in v0.47.0
func (o ManagedConfig) WithCreateIssuesRepos(repos []string) ManagedConfig
WithCreateIssuesRepos returns a copy of o whose create_issues allowlist permits exactly the given repositories. It is how repos install records the upstream-only cross-repo permission on a manifest entry (#8218). The receiver is not modified.
func (ManagedConfig) Writer ¶ added in v0.44.0
func (o ManagedConfig) Writer() PerRepoConfigWriter
Writer returns the managed configuration as a PerRepoConfigWriter, or nil if unset.
type ModelsConfig ¶ added in v0.42.0
type ModelsConfig struct {
// Aliases overrides fullsend's pinned alias table per key.
// Keys are alias names (opus, sonnet, haiku, fable); values are
// model ids or provider/id specs validated with ValidModelRef.
Aliases map[string]string `yaml:"aliases,omitempty"`
}
ModelsConfig groups model-related repo config under a single YAML key. Currently only Aliases; future keys (e.g. defaults, catalog metadata) can be added without flat-key proliferation.
type OpenAIWIFConfig ¶ added in v0.38.0
type OpenAIWIFConfig struct {
Audience string `yaml:"audience,omitempty"`
IdentityProviderID string `yaml:"identity_provider_id,omitempty"`
ServiceAccountID string `yaml:"service_account_id,omitempty"`
}
OpenAIWIFConfig identifies the OpenAI Workload Identity provider and service-account mapping a run exchanges its GitHub OIDC token with.
func (OpenAIWIFConfig) IsZero ¶ added in v0.38.0
func (c OpenAIWIFConfig) IsZero() bool
IsZero reports whether no identifier is set.
func (OpenAIWIFConfig) Missing ¶ added in v0.38.0
func (c OpenAIWIFConfig) Missing() []string
Missing lists the identifiers still unset, in a fixed order, so a partially configured block can be reported precisely.
func (OpenAIWIFConfig) Trimmed ¶ added in v0.38.0
func (c OpenAIWIFConfig) Trimmed() OpenAIWIFConfig
Trimmed returns the identifiers with surrounding whitespace removed, so a whitespace-only YAML value counts as unset.
type PerRepoConfigReader ¶ added in v0.31.0
type PerRepoConfigReader interface {
ConfigReader
ConfigRoles() []string
ConfigRuntime() string
ConfigForge() string
ConfigTracker() string
ConfigMintURL() string
ConfigKeepHistory() bool
ConfigInferenceProvider() string
ConfigInferenceProject() string
ConfigInferenceRegion() string
ConfigInferenceWIFProvider() string
ConfigInferenceOpenAI() OpenAIWIFConfig
// ConfigInferenceGateway returns the effective inference.gateway
// block, layered field by field (ADR 0137).
ConfigInferenceGateway() InferenceGatewayConfig
// ConfigModelAliases returns the effective model alias map, merged
// per-key through the parent chain. nil (the code default) means no
// aliases are configured: every alias resolves through the runtime's
// compiled-in table.
ConfigModelAliases() map[string]string
// IsOwnersFileAuthEnabled reports whether the owners_file
// authorization provider is listed.
IsOwnersFileAuthEnabled() bool
}
PerRepoConfigReader extends ConfigReader with per-repo-specific fields. Methods are prefixed with "Config" to avoid conflicts with the struct field names (Roles and Runtime).
func ParsePerRepoConfig ¶ added in v0.8.0
func ParsePerRepoConfig(data []byte) (PerRepoConfigReader, error)
ParsePerRepoConfig parses YAML bytes into a PerRepoConfigReader.
type PerRepoConfigWriter ¶ added in v0.33.0
type PerRepoConfigWriter interface {
PerRepoConfigReader
ConfigWriter
SetRoles([]string)
SetRuntime(string)
SetMintURL(string)
SetKeepHistory(bool)
SetInferenceProvider(string)
SetInferenceProject(string)
SetInferenceRegion(string)
SetInferenceWIFProvider(string)
SetInferenceOpenAI(OpenAIWIFConfig)
SetInferenceGateway(InferenceGatewayConfig)
// MergeInferenceGateway layers the set fields of g over this layer's
// own inference.gateway block, the way the layers merge.
MergeInferenceGateway(InferenceGatewayConfig)
SetModelAliases(map[string]string)
SetOwnersFileAuthEnabled(bool)
}
PerRepoConfigWriter extends PerRepoConfigReader and ConfigWriter with per-repo-specific mutation methods.
func LayerOnBase ¶ added in v0.44.0
func LayerOnBase(overlay PerRepoConfigWriter, baseYAML []byte) (PerRepoConfigWriter, error)
LayerOnBase returns a writer whose local fields are overlay's and whose parent chain is base → code defaults. baseYAML may be empty, in which case the parent is code defaults only. The overlay is cloned so the caller's value is not mutated.
func MergeManaged ¶ added in v0.44.0
func MergeManaged(parent, child PerRepoConfigWriter) PerRepoConfigWriter
MergeManaged combines two sparse managed-configuration layers using the per-field merge rules of per-repo config. child wins where it sets a value; unspecified child fields inherit from parent. Neither code defaults nor a config.base.yaml layer are baked in. A nil layer is treated as unset.
func NewEmptyPerRepoOverlay ¶ added in v0.36.0
func NewEmptyPerRepoOverlay() PerRepoConfigWriter
NewEmptyPerRepoOverlay creates an empty per-repo config suitable for use as a stub overlay when a preset base layer is provided. No roles, agents, or version are populated; the overlay inherits everything from the base layer via the parent fallback chain.
func NewPerRepoConfig ¶ added in v0.8.0
func NewPerRepoConfig(roles []string, targetRepo string) PerRepoConfigWriter
NewPerRepoConfig creates a new perRepoConfig with the given roles. The returned ConfigWriter provides read-write access to shared config fields; use PerRepoConfigReader type assertion for per-repo-specific methods.
func ParsePerRepoConfigWriter ¶ added in v0.33.0
func ParsePerRepoConfigWriter(data []byte) (PerRepoConfigWriter, error)
ParsePerRepoConfigWriter parses YAML bytes into a PerRepoConfigWriter for callers that need to modify the config after parsing.
func ParsePerRepoConfigWriterLayered ¶ added in v0.38.0
func ParsePerRepoConfigWriterLayered(overlayData []byte, baseData []byte) (PerRepoConfigWriter, error)
ParsePerRepoConfigWriterLayered parses overlay and optional base YAML bytes into a PerRepoConfigWriter with the parent chain overlay → base → code defaults. When baseData is nil the result is equivalent to ParsePerRepoConfigWriter (parent = code defaults only). This is the preferred entry point when both layers are available as raw bytes (e.g. fetched from a forge API) rather than on the local filesystem (where LoadConfigWriter should be used instead).
type PerRepoInferenceConfig ¶ added in v0.36.0
type PerRepoInferenceConfig struct {
Provider string `yaml:"provider,omitempty"`
Project string `yaml:"project,omitempty"`
Region string `yaml:"region,omitempty"`
WIFProvider string `yaml:"wif_provider,omitempty"`
// OpenAI holds the OpenAI Workload Identity Federation identifiers
// (ADR 0092). They are not secrets: the mapping they name only
// trusts a GitHub OIDC token whose claims match, and the run prints
// them. The FULLSEND_OPENAI_* runner variables, when set, take
// precedence over this block.
OpenAI *OpenAIWIFConfig `yaml:"openai,omitempty"`
// Gateway is the inference gateway credential route (ADR 0137): a
// self-hosted gateway that validates the job's forge OIDC token. It
// layers field by field and has no runner-variable override.
Gateway *InferenceGatewayConfig `yaml:"gateway,omitempty"`
}
PerRepoInferenceConfig groups inference backend settings for per-repo configs. The Provider field identifies the inference backend (currently only "vertex"); Project, Region, and WIFProvider hold provider-specific connection details.
type ReactionNotificationConfig ¶ added in v0.38.0
type ReactionNotificationConfig struct {
Start string `yaml:"start,omitempty"`
Completion string `yaml:"completion,omitempty"`
}
ReactionNotificationConfig controls start/completion emoji reactions, an alternative to comments that doesn't generate a GitHub notification. Unlike comments, both fields default to "disabled" — reactions are an opt-in addition rather than a default-on behavior. Valid start values: "enabled", "disabled" (default). Valid completion values: "enabled", "on_failure", "disabled" (default).
type SafetyRelaxation ¶ added in v0.44.0
SafetyRelaxation is one candidate value that is less restrictive than the current effective configuration without an explicit local declaration in the managed configuration (ADR 0122).
func CheckManagedSafetyGate ¶ added in v0.44.0
func CheckManagedSafetyGate(current PerRepoConfigReader, candidate PerRepoConfigWriter) []SafetyRelaxation
CheckManagedSafetyGate compares current and candidate effective configurations (both already layered managed → base → code defaults). A less-restrictive candidate is reported unless candidate declares that relaxation locally. candidate must be the layered *perRepoConfig so omitted vs explicit local fields can be distinguished.
func CheckManagedSafetyGateFromLayerPairs ¶ added in v0.47.0
func CheckManagedSafetyGateFromLayerPairs(currentYAML, currentBaseYAML []byte, candidate PerRepoConfigWriter, candidateBaseYAML []byte) ([]SafetyRelaxation, error)
CheckManagedSafetyGateFromLayerPairs compares the current effective configuration (currentYAML over currentBaseYAML → code defaults) with the proposed one (candidate over candidateBaseYAML → code defaults). Use it when the base layer itself would change (a declared preset replacing an existing .fullsend/config.base.yaml), so a replacement base cannot bypass restrictions through overlay fallthrough. Only fields the candidate overlay declares locally count as explicit relaxations; a base change alone never does.
func CheckManagedSafetyGateFromLayers ¶ added in v0.44.0
func CheckManagedSafetyGateFromLayers(currentYAML []byte, candidate PerRepoConfigWriter, baseYAML []byte) ([]SafetyRelaxation, error)
CheckManagedSafetyGateFromLayers layers currentYAML (the installed .fullsend/config.yaml, or empty when the file is missing) and candidate onto the same parent chain (baseYAML → code defaults) and reports implicit relaxations. Omitted candidate keys fall through the parent chain rather than being ignored because the sparse file lacks them.
func (SafetyRelaxation) String ¶ added in v0.44.0
func (r SafetyRelaxation) String() string
type StatusNotificationConfig ¶ added in v0.15.0
type StatusNotificationConfig struct {
Comment CommentNotificationConfig `yaml:"comment,omitempty"`
Reaction ReactionNotificationConfig `yaml:"reaction,omitempty"`
}
StatusNotificationConfig controls status comments and reactions posted on issues/PRs when agents start and complete.
type StatusNotificationsReader ¶ added in v0.36.0
type StatusNotificationsReader interface {
StatusNotifications() *StatusNotificationConfig
}
StatusNotificationsReader provides read access to status notification configuration (comment start & completion).