Documentation
¶
Overview ¶
Package config is factory-agent's local, owner-controlled configuration (design/workstreams/agent/LLD/supervise.md §The local config): the dispatcher, the pool, the enrollment token file, labels, the harnesses' dedicated config dirs, the owner's lending consent, and how the agent polls for tasks.
The file is YAML 1.2 decoded strictly, the way v1alpha1 decodes the catalog: YAML → JSON → encoding/json with DisallowUnknownFields, so unknown keys, duplicate keys and non-string keys are errors.
Index ¶
- Constants
- func Efforts() []string
- func ExpandPath(p string, home func() (string, error)) (string, error)
- func GiB(v string) int
- func Harnesses() []string
- func HostFrom(hostname string) string
- func KindImageTag(ref string) (tagged string, ok bool)
- func ReadSecretFile(path string) (string, error)
- func ValidWarmImage(ref string) bool
- type Config
- type Harness
- type Options
- type Poll
- type ValidationError
- type WarmImages
- type Workspace
- type WorkspaceSize
Constants ¶
const ( HarnessCodex = "codex" HarnessClaudeCode = "claude-code" )
The harnesses factory-agent has adapters for (harness-adapters.md).
const ( // DefaultPollWait is poll.wait's default, the long poll's. DefaultPollWait = "30s" // DefaultPollInterval is poll.interval's default: poll again at once after a 204. DefaultPollInterval = "0s" )
The poll block's defaults: the long poll (P3 §Agents poll briefly). Its rules are the worker's (worker.Poll.Validate).
const ( DriverTart = "tart" DriverKata = "kata" )
The workspace drivers (P1 §1).
const DefaultGatewayPort = 3128
DefaultGatewayPort is workspace.gatewayPort's default: the port host init's firewall opens and the workspace runner's gateway listens on.
const DefaultPath = "~/.config/factory-agent/agent.yaml"
DefaultPath is where factory-agent looks for its config when --config isn't given.
const DefaultWorkRoot = "~/.factory-agent/work"
DefaultWorkRoot holds the per-task scratch workspaces when workRoot isn't set.
Variables ¶
This section is empty.
Functions ¶
func Efforts ¶
func Efforts() []string
Efforts are the normalised reasoning efforts a harness may offer (harness-adapters.md's effort mappings).
func ExpandPath ¶
ExpandPath expands a leading ~ or ~/ with home.
func GiB ¶
GiB is v, a whole number of GiB with the Gi suffix (workspace.size.memory and .disk, a task's limits.memory), in GiB; 0 when v isn't one.
func HostFrom ¶
HostFrom turns a machine host name into a valid agent host: its first label, lower-cased, with every character outside [a-z0-9-] replaced by '-'.
func KindImageTag ¶
KindImageTag is the reference the warm base saves a kind image as: ref without its @digest, if any. ok is false for a digest without a tag (name@sha256:...).
func ReadSecretFile ¶
ReadSecretFile reads a token file (the enrollment or refresh token): it must be a regular file, not readable or writable by group or others, and non-empty once trimmed. Errors never carry the content.
func ValidWarmImage ¶
ValidWarmImage reports whether ref may be a warm image: at most maxImageLen bytes of an image reference's characters, so no whitespace and no leading -. host init passes it to docker pull, and the kata helper, as root, to nerdctl pull: a leading - would be a flag.
Types ¶
type Config ¶
type Config struct {
// Dispatcher is the dispatcher's base URL (the API is under /api/v1). https, or http on a
// loopback host only: the agent token travels on every call.
Dispatcher string `json:"dispatcher"`
// Pool is the registered Pool to join.
Pool string `json:"pool"`
// EnrollmentTokenFile holds the one-time enrollment token an admin minted with `factory
// agent enroll` (P1 §6), 0600. supervise reads it only while its state dir has no refresh
// token, exchanges it once and re-registers with the refresh token from then on.
EnrollmentTokenFile string `json:"enrollmentTokenFile,omitzero"`
// Host names the agent (agt_<owner>-<host>); default: the machine's short host name,
// lower-cased.
Host string `json:"host,omitzero"`
// Labels are the capability labels to advertise.
Labels []string `json:"labels,omitzero"`
// Harnesses configures each harness by name (codex, claude-code).
Harnesses map[string]Harness `json:"harnesses"`
// WorkRoot holds the per-task scratch workspaces; default ~/.factory-agent/work.
WorkRoot string `json:"workRoot,omitzero"`
// Lending is the owner's consent: what the agent may take. Sent at registration and again
// on SIGHUP.
Lending v1alpha1.Lending `json:"lending"`
// Workspace is the VM workspace setup; `factory-agent host` reads only this block.
Workspace *Workspace `json:"workspace,omitzero"`
// Poll is how the lease loop asks the dispatcher for tasks; Parse fills its defaults
// (the long poll).
Poll Poll `json:"poll,omitzero"`
// Path is the file the config was read from (not a config key).
Path string `json:"-"`
}
Config is the worker's local configuration.
func Load ¶
Load reads, decodes and validates the config at path (a leading ~ is expanded). The file must not be writable by group or others: whoever can write it can point the worker, and the owner's login, at another dispatcher.
func Parse ¶
Parse decodes and validates a config document, fills the defaults and expands ~ in paths.
func (*Config) MaxConcurrent ¶
MaxConcurrent is how many tasks the worker runs at once: lending.maxConcurrent, default 1.
type Harness ¶
type Harness struct {
// Models the owner's plan allows.
Models []string `json:"models"`
// Efforts are the normalised reasoning efforts offered.
Efforts []string `json:"efforts,omitzero"`
// Default is the model used when a task asks for none; one of Models.
Default string `json:"default,omitzero"`
}
Harness is one harness's local config: what the owner's plan allows (harnesses don't reliably list it, 10-poc.md §Capabilities). Its login is the one `factory-agent login` stored, which the VM workspace's gateway adds.
type Options ¶
type Options struct {
// Home expands a leading ~/ in paths. Default os.UserHomeDir.
Home func() (string, error)
// Hostname names the agent when host isn't set. Default os.Hostname.
Hostname func() (string, error)
// Warn gets non-fatal findings (a config readable by others). Default: discarded.
Warn func(string)
// GOOS picks the default workspace driver. Default runtime.GOOS.
GOOS string
}
Options are Load's injectable dependencies.
type Poll ¶ added in v0.2.0
type Poll struct {
// Wait is how long each LeaseTask asks the dispatcher to hold the request: whole seconds
// from 0s to 60s. Default 30s. A wait of 0s needs an interval of at least 1s.
Wait string `json:"wait,omitzero"`
// Interval is how long an idle agent sleeps after a 204 before it polls again; never
// negative. Default 0s. A poll that gets a task polls again at once.
Interval string `json:"interval,omitzero"`
}
Poll is how supervise's lease loop asks the dispatcher for tasks (P3 §Agents poll briefly). The defaults keep the long poll; an agent of a dispatcher where idle time must cost nothing sets wait: 0s and an interval such as 30s.
func (Poll) IntervalDuration ¶ added in v0.2.0
IntervalDuration is poll.interval; 0 when it isn't valid (Parse refuses it then).
func (Poll) WaitDuration ¶ added in v0.2.0
WaitDuration is poll.wait; 0 when it isn't valid (Parse refuses it then).
type ValidationError ¶
ValidationError lists every problem found in a config, each prefixed with its key.
func (*ValidationError) Error ¶
func (e *ValidationError) Error() string
type WarmImages ¶
type WarmImages struct {
Images []string `json:"images,omitzero"`
KindImages []string `json:"kindImages,omitzero"`
}
WarmImages are the images the warm base's Docker cache holds; KindImages are also loaded into kind. A kind image is name:tag, or name:tag@sha256:... to pin it: the warm base pulls it by digest and saves it tagged name:tag, the reference kind's nodes find it by. A digest without a tag (name@sha256:...) is refused, since kind's nodes would have no name for it.
type Workspace ¶
type Workspace struct {
Driver string `json:"driver,omitzero"` // tart | kata; default tart on darwin, kata on linux
Size WorkspaceSize `json:"size,omitzero"`
GatewayPort int `json:"gatewayPort,omitzero"` // default 3128
Warm WarmImages `json:"warm,omitzero"`
}
Workspace is the VM workspace setup (P1 §7): the driver, the per-workspace size, the gateway port and the warm base's images (used from P1 phase 2b).
func LoadWorkspace ¶
LoadWorkspace reads only the workspace block of the config at path, with the defaults filled: `factory-agent host` needs no dispatcher, pool or enrollment token. The file is checked as Load checks it, and unknown keys are still errors; the other blocks aren't validated. A missing file gives the defaults when missingOK is set.
func (Workspace) WithDefaults ¶
WithDefaults fills the unset fields; goos picks the driver.
type WorkspaceSize ¶
type WorkspaceSize struct {
CPUs int `json:"cpus,omitzero"` // default 6
Memory string `json:"memory,omitzero"` // Gi suffix, default 8Gi
Disk string `json:"disk,omitzero"` // Gi suffix, default 60Gi
}
WorkspaceSize is one workspace's VM size.
func (WorkspaceSize) DiskGiB ¶
func (s WorkspaceSize) DiskGiB() int
DiskGiB is size.disk in GiB; 0 when it isn't valid.
func (WorkspaceSize) MemoryGiB ¶
func (s WorkspaceSize) MemoryGiB() int
MemoryGiB is size.memory in GiB; 0 when it isn't valid.