config

package
v0.14.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 9, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package config loads Peen's deployment configuration from PEEN_ variables.

Index

Constants

View Source
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

View Source
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

func Parse() (Config, error)

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

func ParseWorker() (Config, error)

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

func (c Config) DockerSocketPath() string

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

func (c Config) HasDockerAuthority() bool

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) Upstreams

func (c Config) Upstreams() ([]Upstream, error)

Upstreams parses and validates the configured named provider list.

func (Config) Validate

func (c Config) Validate() error

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

func (c Config) ValidateWorker() error

ValidateWorker is Validate without the controller-only state directory rules.

func (Config) WorkerEnvironment added in v0.8.0

func (c Config) WorkerEnvironment() (map[string]string, error)

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

func (c Config) WorkerSocketRoot() string

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

func (c Config) WorkspaceRoots() ([]string, error)

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.

func (Upstream) APIKey

func (u Upstream) APIKey() string

APIKey resolves only the environment variable selected by the operator. Empty is legitimate for intentionally keyless endpoints.

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"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL