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 Upstream
- type UpstreamType
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"`
// WorkspaceRoot is the absolute directory a client may open session
// workspaces under: the root itself or any directory below it. 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. Empty uses the process working directory.
WorkspaceRoot string `env:"PEEN_WORKSPACE_ROOT"`
// RemovedWorkspaceRootsJSON catches the PEEN_WORKSPACE_ROOTS list this
// release replaced, so a deployment still setting it fails at startup
// instead of silently confining sessions to the working directory.
RemovedWorkspaceRootsJSON 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 overrides the image for every Docker profile. Empty leaves
// each profile's image in effect. Any reference the Docker daemon resolves,
// including a local development image, is valid.
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:"5" 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. Peen supports one workspace root, so the list holds exactly one entry: PEEN_WORKSPACE_ROOT, or the process working directory when it is unset. The list shape is what the workspace policy and the HTTP API carry.
The root is resolved through its symlinks, so a request naming an alias of it 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 Upstream ¶
type Upstream struct {
Name string `json:"name"`
Type UpstreamType `json:"type"`
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, and the type is the wire protocol that provider speaks.
type UpstreamType ¶ added in v0.10.0
type UpstreamType string
UpstreamType selects an Elelem driver implementation. It names the wire protocol an upstream speaks, not the vendor behind it. The vendor is the upstream's own Name.
const ( UpstreamTypeOpenAI UpstreamType = "openai" UpstreamTypeAnthropic UpstreamType = "anthropic" UpstreamTypeZAICoding UpstreamType = "zai-coding" )