config

type AgentConfig struct {
	Family       string   `toml:"family"`                  // CLI family ("claude", "codex", "opencode", "gemini", "hermes")
	SecretsScope string   `toml:"secrets_scope,omitempty"` // [secrets.X] section to resolve env from; defaults to instance name
	HomeOverride string   `toml:"home,omitempty"`          // optional HOME override (e.g. "~/.claude-personal") so each instance has its own auth dir
	Tags         []string `toml:"tags,omitempty"`          // labels for tag-routed dispatch ("fast", "long-context", …)
	FailoverTo   []string `toml:"failover_to,omitempty"`   // ordered fallback chain of instance names; failover policy cascades through this list on Send error
	Sandbox      string   `toml:"sandbox,omitempty"`       // ADR-020 / #163: name of a [sandboxes.<name>] profile to wrap every dispatch to this instance in. Empty = no sandbox.
}

type AutoLintConfig struct {
	Enabled *bool `toml:"enabled,omitempty"` // pointer so nil means default-on; explicit false disables
}

type BridgeOverrides struct {
	Plugin string `toml:"plugin,omitempty"` // org/repo of the plugin to install instead of the default
}

type CheckpointConfig struct {
	Guard GuardConfig `toml:"guard,omitempty"`
}

type Config struct {
	CoreTools     map[string]CoreTool        `toml:"core_tools,omitempty"`
	Sources       map[string]Source          `toml:"sources,omitempty"`
	Tools         map[string]ToolOverride    `toml:"tools,omitempty"`
	Tags          map[string]TagRule         `toml:"tags,omitempty"`
	Groups        map[string]GroupDef        `toml:"groups,omitempty"`
	Profile       ProfileConfig              `toml:"profile,omitempty"`
	Agents        map[string]AgentConfig     `toml:"agents,omitempty"`
	Bridges       map[string]BridgeOverrides `toml:"bridge,omitempty"`
	Dispatch      Dispatch                   `toml:"dispatch,omitempty"`
	Observability ObservabilityConfig        `toml:"observability,omitempty"`
	AutoLint      AutoLintConfig             `toml:"auto_lint,omitempty"`
	Hooks         HooksConfig                `toml:"hooks,omitempty"`
	// Telemetry deliberately drops `omitempty` for the same reason
	// TelemetryConfig.Enabled does — a struct that nests a
	// load-bearing `false` must round-trip to disk explicitly.
	// Without this, a fresh `Default()` (Enabled=false, APIKey="",
	// Host="") would write zero-value fields and the encoder would
	// see the whole TelemetryConfig as empty and skip the section
	// entirely, defeating the v0.22.19+ explicit-opt-out path.
	Telemetry     TelemetryConfig          `toml:"telemetry"`
	Portals       map[string]PortalConfig  `toml:"portals,omitempty"`
	Sandboxes     map[string]SandboxConfig `toml:"sandboxes,omitempty"`
	SandboxWorker SandboxWorkerConfig      `toml:"sandbox_worker,omitempty"`
	Peer          PeerConfig               `toml:"peer,omitempty"`
	Checkpoint    CheckpointConfig         `toml:"checkpoint,omitempty"`
	Unattended    UnattendedConfig         `toml:"unattended,omitempty"`
}

type CoreTool struct {
	Enabled *bool `toml:"enabled,omitempty"`
}

type Dispatch struct {
	Mode   string         `toml:"mode,omitempty"`
	Limits DispatchLimits `toml:"limits,omitempty"`
}

type DispatchLimits struct {
	Rate          string `toml:"rate,omitempty"`
	Burst         int    `toml:"burst,omitempty"`
	MaxConcurrent int    `toml:"max_concurrent,omitempty"`
}

type GroupDef struct {
	Include []string `toml:"include,omitempty"`
}

type GuardConfig struct {
	// Enabled gates the entire middleware. Default false; opt-in
	// via wizard or hand-edited config.toml.
	Enabled bool `toml:"enabled,omitempty"`
	// MaxEditsWithoutCheckpoint is the threshold N: once N edits
	// have landed since the last checkpoint, the next pre-edit
	// hook returns ErrCheckpointRequired. Zero or negative → use
	// the package default (5). The hard ceiling is enforced in
	// guard.Check, not here, so config round-trips a literal 0 as
	// "use default" rather than "disable" (Enabled is the disable
	// switch).
	MaxEditsWithoutCheckpoint int `toml:"max_edits_without_checkpoint,omitempty"`
}

type HookEntry struct {
	Cmd        string   `toml:"cmd"`                      // shell snippet evaluated by /bin/sh -c
	Argv       []string `toml:"argv,omitempty"`           // alternative: raw argv (skips the shell)
	TimeoutMs  int      `toml:"timeout_ms,omitempty"`     // per-hook hard cap; default 5000
	BlockOnErr bool     `toml:"block_on_error,omitempty"` // when true, hook failure errors out the originating op
}

type HooksConfig struct {
	Events map[string][]HookEntry `toml:"events,omitempty"`
}

type InstanceOverride struct {
	Mode string `toml:"mode,omitempty"`
}

type ObservabilityConfig struct {
	Enabled     bool    `toml:"enabled,omitempty"`      // master gate; default false
	ExporterURL string  `toml:"exporter_url,omitempty"` // OTLP/HTTP endpoint (e.g. http://localhost:4318)
	SampleRate  float64 `toml:"sample_rate,omitempty"`  // [0.0, 1.0]; 0 or unset → 1.0 when enabled

	// Langfuse-style auth headers. When LangfusePublicKey + Secret are
	// set, the exporter sends `Authorization: Basic base64(public:secret)`
	// and Langfuse picks the spans up via its OTel ingest endpoint. Empty
	// means a generic OTLP collector with no auth.
	LangfuseHost      string `toml:"langfuse_host,omitempty"`
	LangfusePublicKey string `toml:"langfuse_public_key,omitempty"`
	LangfuseSecretKey string `toml:"langfuse_secret_key,omitempty"`

	// ServiceName tags the resource emitted on every span. Defaults
	// to "clawtool" when empty.
	ServiceName string `toml:"service_name,omitempty"`
}

type PeerConfig struct {
	// AutoClosePanes is a pointer so nil means default-on. An
	// explicit `false` (operator opt-out) round-trips to disk and
	// flips agents.SetAutoClosePanes(false) at boot, leaving every
	// auto-spawned pane open after its dispatch terminates.
	AutoClosePanes *bool `toml:"auto_close_panes,omitempty"`

	// AutoCloseGraceSeconds defers the kill-pane after a task lands
	// in terminal status by N seconds. Default 0 = immediate close
	// (legacy behaviour). When > 0, the lifecycle hook schedules
	// the kill via time.AfterFunc and cancels the timer if a fresh
	// dispatch lands on the same auto-spawned peer before the
	// grace window elapses (so back-to-back tasks don't kill the
	// pane mid-second-task). Negative values are treated as 0.
	AutoCloseGraceSeconds int `toml:"auto_close_grace_seconds,omitempty"`
}

type PortalBrowserSettings struct {
	Stealth        bool   `toml:"stealth,omitempty"`
	ViewportWidth  int    `toml:"viewport_width,omitempty"`
	ViewportHeight int    `toml:"viewport_height,omitempty"`
	Locale         string `toml:"locale,omitempty"`
}

type PortalConfig struct {
	Name                  string                `toml:"name,omitempty"`
	BaseURL               string                `toml:"base_url"`
	StartURL              string                `toml:"start_url,omitempty"` // defaults to BaseURL
	SecretsScope          string                `toml:"secrets_scope"`       // points at [scopes."portal.<name>"] in secrets.toml
	AuthCookieNames       []string              `toml:"auth_cookie_names,omitempty"`
	TimeoutMs             int                   `toml:"timeout_ms,omitempty"` // default 180000
	LoginCheck            PortalPredicate       `toml:"login_check,omitempty"`
	ReadyPredicate        PortalPredicate       `toml:"ready_predicate,omitempty"`
	Selectors             PortalSelectors       `toml:"selectors"`
	ResponseDonePredicate PortalPredicate       `toml:"response_done_predicate"`
	Headers               map[string]string     `toml:"headers,omitempty"`
	Browser               PortalBrowserSettings `toml:"browser,omitempty"`
}

type PortalPredicate struct {
	Type  string `toml:"type"`            // selector_exists | selector_visible | eval_truthy
	Value string `toml:"value,omitempty"` // selector or JS expression depending on Type
}

type PortalSelectors struct {
	Input    string `toml:"input"`              // textarea / input the prompt goes into
	Submit   string `toml:"submit,omitempty"`   // submit button; optional when Enter dispatch is used
	Response string `toml:"response,omitempty"` // last-rendered assistant message container
}

type ProfileConfig struct {
	Active string `toml:"active,omitempty"`
}

type Resolution struct {
	Enabled bool
	Rule    string // "tools.<sel>", "core_tools.<name>", "default"
}

type SandboxConfig struct {
	Description string         `toml:"description,omitempty"`
	Paths       []SandboxPath  `toml:"paths,omitempty"`
	Network     SandboxNetwork `toml:"network,omitempty"`
	Limits      SandboxLimits  `toml:"limits,omitempty"`
	Env         SandboxEnv     `toml:"env,omitempty"`
}

type SandboxEnv struct {
	Allow []string `toml:"allow,omitempty"`
	Deny  []string `toml:"deny,omitempty"`
}

type SandboxLimits struct {
	Timeout      string `toml:"timeout,omitempty"`
	Memory       string `toml:"memory,omitempty"`
	CPUShares    int    `toml:"cpu_shares,omitempty"`
	ProcessCount int    `toml:"process_count,omitempty"`
}

type SandboxNetwork struct {
	Policy string   `toml:"policy,omitempty"`
	Allow  []string `toml:"allow,omitempty"`
}

type SandboxPath struct {
	Path string `toml:"path"`
	Mode string `toml:"mode"`
}

type SandboxWorkerConfig struct {
	// Mode is "off" (default), "host" (worker on the same host),
	// or "container" (worker reachable over the network at URL).
	Mode string `toml:"mode,omitempty"`
	// URL is the worker's WebSocket endpoint, e.g.
	// "ws://127.0.0.1:2024/ws". Required when Mode != "off".
	URL string `toml:"url,omitempty"`
	// TokenFile is the path to the bearer-token file shared with
	// the worker. Default $XDG_CONFIG_HOME/clawtool/worker-token.
	TokenFile string `toml:"token_file,omitempty"`
	// AutoStart asks the daemon to spawn `clawtool sandbox-worker`
	// (or pull + run a container, future work) when no live
	// worker is reachable. Phase 1 surfaces the flag but does not
	// implement spawn — operator runs the worker manually.
	AutoStart bool `toml:"auto_start,omitempty"`
	// Image is the docker image tag the operator built (or
	// pulled) for the worker container. Phase 2 will use it for
	// auto_start; Phase 1 stores it as documentation.
	Image string `toml:"image,omitempty"`
}

type Source struct {
	Type    string            `toml:"type"`              // currently only "mcp"
	Command []string          `toml:"command,omitempty"` // argv to spawn the MCP server
	Env     map[string]string `toml:"env,omitempty"`     // env vars (`${VAR}` expansion at use)
}

type TagRule struct {
	Match    []string `toml:"match,omitempty"`
	Disabled bool     `toml:"disabled,omitempty"`
	Enabled  bool     `toml:"enabled,omitempty"`
}

type TelemetryConfig struct {
	// Enabled deliberately drops `omitempty` — `false` is a load-
	// bearing value (explicit opt-out) that must round-trip to
	// disk so the v0.22.19+ upgrade-merge logic in Load() can
	// distinguish "user wrote enabled = false" from "user wrote
	// nothing, defaults apply." With omitempty, `false` was
	// silently stripped on Save and the next Load saw an absent
	// key, which mergeDefaults then patched back to true — the
	// `clawtool telemetry off` verb appeared to no-op across
	// restarts.
	Enabled bool   `toml:"enabled"`
	APIKey  string `toml:"api_key,omitempty"` // PostHog project key (optional; defaults baked into the binary at release time)
	Host    string `toml:"host,omitempty"`    // override the default https://app.posthog.com endpoint
}

type ToolListEntry struct {
	Selector   string
	Resolution Resolution
}

type ToolOverride struct {
	Enabled *bool `toml:"enabled,omitempty"`
}

type UnattendedConfig struct {
	Mode      string                      `toml:"mode,omitempty"`
	Overrides map[string]InstanceOverride `toml:"overrides,omitempty"`
}