Documentation
¶
Overview ¶
Package config loads Peen's deployment configuration from PEEN_ variables.
Index ¶
- Constants
- Variables
- type CompactionMode
- type Config
- func (c Config) DockerSocketPath() string
- func (c Config) ExecutionProfiles() (*worker.ProfileSet, error)
- func (c Config) HasDockerAuthority() bool
- func (c Config) Upstreams() ([]Upstream, error)
- func (c Config) Validate() error
- func (c Config) ValidateWorker() error
- func (c Config) WorkerEnvironment() (map[string]string, error)
- func (c Config) WorkerSocketRoot() string
- func (c Config) WorkspaceRoots() ([]string, error)
- type ExecutionMount
- type ExecutionProfile
- type ProviderType
- type Upstream
Constants ¶
const ( // DefaultDockerSocketPath is the host socket a controller uses to create // worker containers. It is the controller's own grant, separate from the // socket a host-like profile may mount into a worker. DefaultDockerSocketPath = "/var/run/docker.sock" )
Variables ¶
var ( // ErrInvalidConfig reports invalid deployment configuration. ErrInvalidConfig = errors.New("invalid Peen configuration") // ErrInvalidUpstream reports malformed named LLM provider configuration. ErrInvalidUpstream = errors.New("invalid Peen upstream") )
Functions ¶
This section is empty.
Types ¶
type CompactionMode ¶
type CompactionMode string
CompactionMode determines how Peen handles an over-budget transcript.
const ( CompactionModeDropOldest CompactionMode = "drop-oldest" CompactionModeSummarize CompactionMode = "summarize" )
type Config ¶
type Config struct {
// ConfigDirectory is the global configuration and harness directory. It is
// the one directory every worker receives, read-only, so it holds only what
// a worker is meant to read: AGENTS.md, .agents, SYSTEM.md,
// APPEND_SYSTEM.md, and COMPACTION.md. Controller runtime state never lives
// here, because mounting this directory into a worker hands that worker
// everything inside it.
ConfigDirectory string `env:"PEEN_CONFIG_DIR,required"`
// StateDirectory is the controller's own durable runtime state: SQLite,
// audit logs, worker socket roots, and controller-only credentials. No
// worker ever receives it. Keeping it out of ConfigDirectory is what stops
// a Docker worker from reading another session's transcript through its
// configuration mount.
//
// The tag carries no `required` because Parse and ParseWorker need
// different answers and gonfiguration decides that at parse time. A
// controller requires it through Validate. A worker owns no durable state,
// so ParseWorker leaves it empty and nothing reads it.
StateDirectory string `env:"PEEN_STATE_DIR"`
WorkingDirectory string
Agent string `default:"default" env:"PEEN_AGENT"`
UpstreamsJSON string `env:"PEEN_UPSTREAMS,required"`
DefaultModel string `env:"PEEN_DEFAULT_MODEL,required"`
CompactionModel string `env:"PEEN_COMPACTION_MODEL"`
// WorkspaceRootsJSON is the operator's allowlist of directories a client
// may open as a session workspace, given as a JSON array of absolute
// paths. It bounds which host directories the control surface will ever
// expose to a session, so it is deployment configuration and never comes
// from a client request. An empty value allows only the process working
// directory, which is the single-workspace behavior it generalizes.
WorkspaceRootsJSON string `env:"PEEN_WORKSPACE_ROOTS"`
// ExecutionProfilesJSON defines the execution profiles a client may name,
// as a JSON array. Every worker capability lives here: image, mounts,
// network, Docker socket, and privilege escalation. None of it ever comes
// from model output or a client request, which only names a profile.
//
// An empty value defines the single native profile, so a deployment that
// configures nothing runs on the host as it always has.
ExecutionProfilesJSON string `env:"PEEN_EXECUTION_PROFILES"`
// DefaultExecutionProfile is the profile a session opened without naming
// one runs under. Empty takes the native profile.
DefaultExecutionProfile string `env:"PEEN_DEFAULT_EXECUTION_PROFILE"`
// WorkerSocketDirectory is the root holding one private directory per
// session worker. Empty puts it under the state directory, because a
// socket root is controller runtime state and a worker receives only its
// own session's directory, never the root.
WorkerSocketDirectory string `env:"PEEN_WORKER_SOCKET_DIR"`
// DockerSocket is the controller's own Docker socket, used to create
// worker containers for a Docker profile. Empty resolves DOCKER_HOST and
// then the platform default. Without a reachable socket a Docker profile
// is refused rather than run natively.
DockerSocket string `env:"PEEN_DOCKER_SOCKET"`
// HostUsername and HostHome describe the host account when a controller
// itself runs in Docker as an arbitrary numeric UID and GID. In that case
// the controller container has no passwd entry for the host account, but a
// Docker worker still has to recreate the account before it can safely
// write workspace files with host ownership. They are both empty for a
// native controller, which resolves its account from the operating system.
HostUsername string `env:"PEEN_HOST_USERNAME"`
HostHome string `env:"PEEN_HOST_HOME"`
// WorkerImage pins one psyb0t/peen image for every Docker profile. Empty
// makes each Docker profile name its own. Either way the value must be an
// immutable psyb0t/peen digest reference, because the worker container
// starts as root and only the Peen entrypoint drops back down.
WorkerImage string `env:"PEEN_WORKER_IMAGE"`
MaxContextTokens int `default:"32768" env:"PEEN_MAX_CONTEXT_TOKENS"` //nolint:lll // Immutable env tag.
CompactionMode CompactionMode `default:"drop-oldest" env:"PEEN_COMPACTION_MODE"` //nolint:lll // Immutable env tag.
CompactionOutputTokens int `default:"2048" env:"PEEN_COMPACTION_MAX_OUTPUT_TOKENS"` //nolint:lll // Immutable env tag.
CompactionTimeout time.Duration `default:"2m" env:"PEEN_COMPACTION_TIMEOUT"` //nolint:lll // Immutable env tag.
TurnTimeout time.Duration `default:"10m" env:"PEEN_TURN_TIMEOUT"` //nolint:lll // Immutable env tag.
// MaxConcurrentTurns bounds how many turns may run at once across every
// session in this process, unlike MaxConcurrentAgentRunsPerSession, which
// only bounds one session's child-agent runs.
MaxConcurrentTurns int `default:"16" env:"PEEN_MAX_CONCURRENT_TURNS"` //nolint:lll // Immutable env tag.
// MaxQueuedUserMessages bounds messages accepted while a session has a
// running turn. They are delivered at an eligible provider round boundary.
MaxQueuedUserMessages int `default:"16" env:"PEEN_MAX_QUEUED_USER_MESSAGES"` //nolint:lll // Immutable env tag.
// MaxMessageBytes bounds the caller-supplied "message" field in a
// message.send event. MaxSystemPromptBytes bounds its optional
// "systemPrompt.content" field. MaxStoredMessageBytes bounds any single
// message row, of any role, before it is written to the durable
// transcript, since a stored assistant or tool message is not otherwise
// bounded by a caller-facing setting.
MaxMessageBytes int `default:"262144" env:"PEEN_MAX_MESSAGE_BYTES"` //nolint:lll // Immutable env tag.
MaxSystemPromptBytes int `default:"65536" env:"PEEN_MAX_SYSTEM_PROMPT_BYTES"` //nolint:lll // Immutable env tag.
MaxStoredMessageBytes int `default:"1048576" env:"PEEN_MAX_STORED_MESSAGE_BYTES"` //nolint:lll // Immutable env tag.
MaxToolRounds int `default:"32" env:"PEEN_MAX_TOOL_ROUNDS"` //nolint:lll // Immutable env tag.
MaxConcurrentTools int `default:"4" env:"PEEN_MAX_CONCURRENT_TOOLS"` //nolint:lll // Immutable env tag.
ToolTimeout time.Duration `default:"15m" env:"PEEN_TOOL_TIMEOUT"` //nolint:lll // Immutable env tag.
MaxToolResultTokens int `default:"8192" env:"PEEN_MAX_TOOL_RESULT_TOKENS"` //nolint:lll // Immutable env tag.
EnableWorkspaceHooks bool `default:"false" env:"PEEN_ENABLE_WORKSPACE_HOOKS"` //nolint:lll // Immutable env tag.
HookCommandTimeout time.Duration `default:"30s" env:"PEEN_HOOK_COMMAND_TIMEOUT"` //nolint:lll // Immutable env tag.
MaxHookCommandOutput int `default:"65536" env:"PEEN_MAX_HOOK_COMMAND_OUTPUT"` //nolint:lll // Immutable env tag.
ToolMaxListEntries int `default:"1000" env:"PEEN_TOOL_MAX_LIST_ENTRIES"` //nolint:lll // Immutable env tag.
ToolMaxListDepth int `default:"16" env:"PEEN_TOOL_MAX_LIST_DEPTH"` //nolint:lll // Immutable env tag.
ToolMaxSearchMatches int `default:"200" env:"PEEN_TOOL_MAX_SEARCH_MATCHES"` //nolint:lll // Immutable env tag.
ToolMaxSearchFileBytes int64 `default:"2097152" env:"PEEN_TOOL_MAX_SEARCH_FILE_BYTES"` //nolint:lll // Immutable env tag.
ToolMaxReadBytes int `default:"262144" env:"PEEN_TOOL_MAX_READ_BYTES"` //nolint:lll // Immutable env tag.
ToolMaxReadLines int `default:"2000" env:"PEEN_TOOL_MAX_READ_LINES"` //nolint:lll // Immutable env tag.
ToolMaxWriteBytes int `default:"4194304" env:"PEEN_TOOL_MAX_WRITE_BYTES"` //nolint:lll // Immutable env tag.
ToolMaxEdits int `default:"64" env:"PEEN_TOOL_MAX_EDITS"` //nolint:lll // Immutable env tag.
ToolMaxDiffBytes int `default:"65536" env:"PEEN_TOOL_MAX_DIFF_BYTES"` //nolint:lll // Immutable env tag.
ToolMaxRemoveEntries int `default:"20000" env:"PEEN_TOOL_MAX_REMOVE_ENTRIES"` //nolint:lll // Immutable env tag.
ToolMaxCommandOutputBytes int `default:"65536" env:"PEEN_TOOL_MAX_COMMAND_OUTPUT_BYTES"` //nolint:lll // Immutable env tag.
ToolCommandTimeout time.Duration `default:"2m" env:"PEEN_TOOL_COMMAND_TIMEOUT"` //nolint:lll // Immutable env tag.
ToolMaxCommandTimeout time.Duration `default:"15m" env:"PEEN_TOOL_MAX_COMMAND_TIMEOUT"` //nolint:lll // Immutable env tag.
MaxPendingEvents int `default:"256" env:"PEEN_MAX_PENDING_EVENTS"` //nolint:lll // Immutable env tag.
MaxEventSummaryBytes int `default:"4096" env:"PEEN_MAX_EVENT_SUMMARY_BYTES"` //nolint:lll // Immutable env tag.
MaxEventDataBytes int `default:"65536" env:"PEEN_MAX_EVENT_DATA_BYTES"` //nolint:lll // Immutable env tag.
MaxEventWakesPerHour int `default:"60" env:"PEEN_MAX_EVENT_WAKES_PER_HOUR"` //nolint:lll // Immutable env tag.
MaxChildAgentDepth int `default:"3" env:"PEEN_MAX_CHILD_AGENT_DEPTH"` //nolint:lll // Immutable env tag.
MaxChildAgentTurns int `default:"16" env:"PEEN_MAX_CHILD_AGENT_TURNS"` //nolint:lll // Immutable env tag.
MaxConcurrentAgentRunsPerSession int `default:"4" env:"PEEN_MAX_CONCURRENT_AGENT_RUNS"` //nolint:lll // Immutable env tag.
MaxAgentRunEventCount int `default:"2000" env:"PEEN_MAX_AGENT_RUN_EVENT_COUNT"` //nolint:lll // Immutable env tag.
MaxAgentRunEventBytes int `default:"65536" env:"PEEN_MAX_AGENT_RUN_EVENT_BYTES"` //nolint:lll // Immutable env tag.
MaxAdHocAgentInstructionBytes int `default:"65536" env:"PEEN_MAX_ADHOC_AGENT_INSTRUCTION_BYTES"` //nolint:lll // Immutable env tag.
HTTPListenAddress string `default:":8080" env:"PEEN_HTTP_LISTEN_ADDRESS"` //nolint:lll // Immutable env tag.
MetricsListenAddress string `default:"127.0.0.1:9090" env:"PEEN_METRICS_LISTEN_ADDRESS"` //nolint:lll // Immutable env tag.
APIToken string `env:"PEEN_API_TOKEN"`
}
Config is the deployment-owned configuration. Provider credentials stay in individually named environment variables, never inside PEEN_UPSTREAMS.
func Parse ¶
Parse reads and validates the fixed PEEN_ environment bindings for a controller. It requires PEEN_STATE_DIR and enforces its separation from PEEN_CONFIG_DIR.
func ParseWorker ¶ added in v0.8.0
ParseWorker reads the same bindings for a session worker.
A worker owns no durable state, so PEEN_STATE_DIR is neither required nor used. The controller keeps it out of a Docker worker's environment on purpose, and a native worker that inherits it still opens no database.
func (Config) DockerSocketPath ¶ added in v0.8.0
DockerSocketPath is the controller's own Docker socket.
An explicit setting wins. Otherwise a `unix://` DOCKER_HOST names the socket, and failing that the platform default is used. A DOCKER_HOST naming anything other than a Unix socket yields an empty path, because this build only launches workers through a local socket it can verify.
func (Config) ExecutionProfiles ¶ added in v0.8.0
func (c Config) ExecutionProfiles() (*worker.ProfileSet, error)
ExecutionProfiles returns the deployment's allowed execution profiles.
An unset PEEN_EXECUTION_PROFILES yields the single native profile, so a deployment that configures nothing keeps running on the host.
func (Config) HasDockerAuthority ¶ added in v0.8.0
HasDockerAuthority reports whether this controller can create worker containers.
It is a real check against the socket rather than a configuration flag, because an operator naming a Docker profile needs to know now, at startup, whether that profile can ever run. A deployment without authority refuses Docker profiles outright and never falls back to a native worker.
func (Config) Validate ¶
Validate checks values which need cross-field or filesystem-aware rules. It is the controller's contract and requires a state directory.
func (Config) ValidateWorker ¶ added in v0.8.0
ValidateWorker is Validate without the controller-only state directory rules.
func (Config) WorkerEnvironment ¶ added in v0.8.0
WorkerEnvironment returns exactly the deployment settings a worker needs.
A Docker worker is a separate process with an intentionally small environment. It needs the same runtime limits, model selection, provider definitions, and named provider credentials as a native worker, but it must not inherit controller-only paths or authority. The allowlist makes that boundary visible and prevents a future PEEN_ control setting from quietly becoming a worker capability.
func (Config) WorkerSocketRoot ¶ added in v0.8.0
WorkerSocketRoot is the directory holding one private directory per session worker.
It is controller runtime state, so it defaults under PEEN_STATE_DIR and never under PEEN_CONFIG_DIR. No worker receives this root: a Docker worker is given only its own session's directory beneath it, so it never learns another session's socket path.
func (Config) WorkspaceRoots ¶ added in v0.8.0
WorkspaceRoots returns the canonical directories a client may open a session under. An unset PEEN_WORKSPACE_ROOTS yields the process working directory, so a deployment that never configures roots still confines sessions to the directory it was started in.
Every root is resolved through its symlinks, so a request naming an alias of an allowed root compares equal to it rather than being refused.
type ExecutionMount ¶ added in v0.8.0
type ExecutionMount struct {
Source string `json:"source"`
Target string `json:"target"`
ReadOnly bool `json:"readOnly"`
}
ExecutionMount is one extra path a profile exposes. An empty target means the worker sees the source at its own absolute path.
type ExecutionProfile ¶ added in v0.8.0
type ExecutionProfile struct {
Name string `json:"name"`
Kind string `json:"kind"`
Revision int64 `json:"revision"`
Image string `json:"image"`
Mounts []ExecutionMount `json:"mounts"`
AllowDockerSocket bool `json:"allowDockerSocket"`
AllowNetwork bool `json:"allowNetwork"`
AllowPrivilegeEscalation bool `json:"allowPrivilegeEscalation"`
}
ExecutionProfile is one operator-defined profile as it appears in PEEN_EXECUTION_PROFILES.
This is the only place a Docker capability can be turned on. A client names a profile; it never sends an image, a mount, a network setting, or a socket request.
type ProviderType ¶
type ProviderType string
ProviderType selects an Elelem driver implementation.
const ( ProviderTypeOpenAI ProviderType = "openai" ProviderTypeAnthropic ProviderType = "anthropic" ProviderTypeZAICoding ProviderType = "zai-coding" )
type Upstream ¶
type Upstream struct {
Name string `json:"name"`
Provider ProviderType `json:"provider"`
BaseURL string `json:"baseUrl"`
APIKeyEnv string `json:"apiKeyEnv"`
}
Upstream configures one deployment-owned named provider. The name is Peen's stable prefix in qualified model references such as aigate/model-name.