config

type A2APeerConfig struct {
	URL                   string        `yaml:"url"`
	TrustTier             int           `yaml:"trust_tier"`
	LatencyTierMS         int           `yaml:"latency_tier_ms"`
	AllowInsecureLoopback bool          `yaml:"allow_insecure_loopback,omitempty"`
	AgentCardTTL          time.Duration `yaml:"agent_card_ttl,omitempty"`
}

type ArtifactsConfig struct {
	Driver                    string `yaml:"driver"`
	FSRoot                    string `yaml:"fs_root,omitempty"`
	DSN                       string `yaml:"dsn,omitempty" secret:"true"`
	HeavyOutputThresholdBytes int    `yaml:"heavy_output_threshold_bytes,omitempty"`
	S3Bucket                  string `yaml:"s3_bucket,omitempty"`
	S3Endpoint                string `yaml:"s3_endpoint,omitempty"`
	S3Region                  string `yaml:"s3_region,omitempty"`
	S3Prefix                  string `yaml:"s3_prefix,omitempty"`
	S3AccessKeyID             string `yaml:"s3_access_key_id,omitempty" secret:"true"`
	S3SecretAccessKey         string `yaml:"s3_secret_access_key,omitempty" secret:"true"`
	S3UsePathStyle            bool   `yaml:"s3_use_path_style,omitempty"`
}

type AuditConfig struct{}

type CLIConfig struct {
	DevHotReload DevHotReloadConfig `yaml:"dev_hot_reload,omitempty"`
}

type Config struct {
	Server      ServerConfig      `yaml:"server"`
	Identity    IdentityConfig    `yaml:"identity"`
	Telemetry   TelemetryConfig   `yaml:"telemetry"`
	State       StateConfig       `yaml:"state"`
	LLM         LLMConfig         `yaml:"llm"`
	Governance  GovernanceConfig  `yaml:"governance"`
	Distributed DistributedConfig `yaml:"distributed,omitempty"`

	// Reserved slots for future phases — owning phase fills the body.
	Runtime   RuntimeConfig   `yaml:"runtime,omitempty"`   // owned by runtime/* phases
	Memory    MemoryConfig    `yaml:"memory,omitempty"`    // owned by memory phases
	Skills    SkillsConfig    `yaml:"skills,omitempty"`    // owned by skills phases
	Tasks     TasksConfig     `yaml:"tasks,omitempty"`     // owned by tasks phases
	Sessions  SessionsConfig  `yaml:"sessions,omitempty"`  // owned by sessions phases
	Artifacts ArtifactsConfig `yaml:"artifacts,omitempty"` // owned by artifacts phases
	Events    EventsConfig    `yaml:"events,omitempty"`    // owned by events phases
	Audit     AuditConfig     `yaml:"audit,omitempty"`     // owned by the audit subsystem
	Protocol  ProtocolConfig  `yaml:"protocol,omitempty"`  // owned by protocol phases
	CLI       CLIConfig       `yaml:"cli,omitempty"`       // owned by CLI phases
	Tools     ToolsConfig     `yaml:"tools,omitempty"`     // owned by tools subsystem phases (26 / 27 / 28 / 29)
	Planner   PlannerConfig   `yaml:"planner,omitempty"`   // owned by the planner subsystem

	// Multimodal is the attachment-handling policy block.
	// Optional; an omitted block keeps the runtime default
	// (image/* inline, everything else ref).
	Multimodal MultimodalConfig `yaml:"multimodal,omitempty"`

	// Embeddings is the embedding-client block — the model/provider
	// pair Harbor turns text into vectors with, configured separately
	// from the chat `llm` block. Optional; REQUIRED (validated) when
	// any semantic-retrieval mode is enabled (`memory.retrieval` /
	// `skills.retrieval` = `semantic`).
	Embeddings EmbeddingsConfig `yaml:"embeddings,omitempty"`

	PauseResume PauseResumeConfig `yaml:"pauseresume,omitempty"` // owned by the pause/resume subsystem
	// contains filtered or unexported fields
}

type CustomToolConfig struct {
	Name        string            `yaml:"name"`
	Description string            `yaml:"description"`
	Input       map[string]string `yaml:"input,omitempty"`
	Output      map[string]string `yaml:"output,omitempty"`
}

type DevHotReloadConfig struct {
	Enabled      *bool         `yaml:"enabled,omitempty"`
	Policy       string        `yaml:"policy,omitempty"`
	DrainTimeout time.Duration `yaml:"drain_timeout,omitempty"`
	WatchRoots   []string      `yaml:"watch_roots,omitempty"`
}

type DistributedConfig struct {
	BusDriver    string `yaml:"bus_driver"`
	RemoteDriver string `yaml:"remote_driver"`
	// BusPollInterval tunes how often the durable bus driver scans the
	// shared StateStore for envelopes published by other instances (or
	// left by a crash) to project onto the local event bus. Optional;
	// the durable driver applies a built-in default when unset (<= 0).
	// Ignored by the loopback driver.
	BusPollInterval time.Duration `yaml:"bus_poll_interval,omitempty"`
}

type EmbeddingsConfig struct {
	Driver     string        `yaml:"driver,omitempty"`
	Provider   string        `yaml:"provider,omitempty"`
	Model      string        `yaml:"model,omitempty"`
	APIKey     string        `yaml:"api_key,omitempty" secret:"true"`
	BaseURL    string        `yaml:"base_url,omitempty"`
	Timeout    time.Duration `yaml:"timeout,omitempty"`
	Dimensions int           `yaml:"dimensions,omitempty"`
}

type EventsConfig struct {
	Driver                   string        `yaml:"driver"`
	MaxSubscribersPerSession int           `yaml:"max_subscribers_per_session"`
	SubscriberBufferSize     int           `yaml:"subscriber_buffer_size"`
	IdleTimeout              time.Duration `yaml:"idle_timeout"`
	DropWindow               time.Duration `yaml:"drop_window"`
	ReplayBufferSize         int           `yaml:"replay_buffer_size"`
	StateDriver              string        `yaml:"state_driver,omitempty"`
	StateDSN                 string        `yaml:"state_dsn,omitempty" secret:"true"`
}

type GovernanceConfig struct {
	RepairAttempts int `yaml:"repair_attempts"`

	// DefaultTier is the tier name applied to an identity that does
	// not match a custom resolver mapping. Empty = no default tier =
	// no enforcement for unmatched identities (latent default).
	DefaultTier string `yaml:"default_tier,omitempty"`

	// IdentityTiers maps tier name to its policy bundle. Empty is the
	// latent default (no enforcement); populated tiers are
	// enforced at the LLM edge AND projected on the read-only posture
	// surface (see the type godoc above). Each entry's fields are
	// independently declared — `budget_ceiling_usd` for cost ceilings,
	// plus rate-limit + MaxTokens fields.
	IdentityTiers map[string]GovernanceTierConfig `yaml:"identity_tiers,omitempty"`
}

type GovernanceRateLimitConfig struct {
	Capacity       int           `yaml:"capacity,omitempty"`
	RefillTokens   int           `yaml:"refill_tokens,omitempty"`
	RefillInterval time.Duration `yaml:"refill_interval,omitempty"`
}

type GovernanceTierConfig struct {
	BudgetCeilingUSD float64                   `yaml:"budget_ceiling_usd,omitempty"`
	RateLimit        GovernanceRateLimitConfig `yaml:"rate_limit,omitempty"`
	MaxTokens        int                       `yaml:"max_tokens,omitempty"`
}

type IdentityConfig struct {
	JWTAlgorithms []string `yaml:"jwt_algorithms"`
	Issuer        string   `yaml:"issuer"`
	Audience      string   `yaml:"audience"`
	JWKSURL       string   `yaml:"jwks_url,omitempty"`
	JWKSFile      string   `yaml:"jwks_file,omitempty"`
	// JWKSMaxStale bounds how long a cached JWKS key snapshot is honored
	// without a successful refresh. Past this age the validator fails
	// closed (rejects tokens with a distinct staleness reason) rather
	// than serving a possibly-revoked key during a prolonged IdP outage.
	// Zero (the default when omitted) applies the safe built-in ceiling;
	// a negative or below-floor value is a validation error. There is no
	// "disable" path — Harbor's posture is fail-closed; the field tunes
	// the ceiling, it does not remove it. This BOUNDS — it does not make
	// instantaneous — key revocation: pair a tight ceiling with
	// overlapping IdP signing keys and short token TTLs.
	JWKSMaxStale time.Duration `yaml:"jwks_max_stale,omitempty"`
}

type InferenceBrokerConfig struct {
	// Name is the operator-facing broker identifier (unique within the
	// slice; referenced by non-secret name from `credential_source: remote`
	// and from a Protocol-installed provider descriptor). Required.
	Name string `yaml:"name"`
	// CredentialURL is the boot-pinned coordinator credential-pull endpoint
	// the runtime GETs the provider API key from. Required; must be https
	// (or a loopback host for the dev / fixture case). The pull carries the
	// runtime's own service bearer token (AuthTokenEnv), so TLS is
	// mandatory off loopback (§7). Boot-pinned: never wire-writable.
	CredentialURL string `yaml:"credential_url"`
	// AuthTokenEnv names the env var holding the runtime's OWN broker
	// credential — the `Authorization: Bearer` the runtime presents to
	// CredentialURL (§7 rule 2 — never hardcoded). Required non-empty. Read
	// lazily at fetch time so a rotated token is picked up without restart.
	AuthTokenEnv string `yaml:"auth_token_env"`
	// Audience is the boot-pinned audience ceiling for the pulled provider
	// key. Optional — an LLM provider key is not always audience-shaped;
	// when present it is enforced as the credential-plane sink pin, when absent the
	// broker's own binding governs. Boot-pinned, never wire-writable.
	Audience string `yaml:"audience,omitempty"`
	// ScopeCeiling is the boot-pinned scope ceiling for the pulled provider
	// key. Optional (see Audience). Boot-pinned, never wire-writable.
	ScopeCeiling []string `yaml:"scope_ceiling,omitempty"`
	// CacheTTL caps the in-memory serve horizon for a brokered provider
	// key. Optional; zero = driver default.
	CacheTTL time.Duration `yaml:"cache_ttl,omitempty"`
	// Timeout bounds a single credential pull. Optional; zero = driver
	// default.
	Timeout time.Duration `yaml:"timeout,omitempty"`
}

type LLMConfig struct {
	Driver               string                           `yaml:"driver"`
	Provider             string                           `yaml:"provider"`
	Model                string                           `yaml:"model"`
	APIKey               string                           `yaml:"api_key" secret:"true"`
	BaseURL              string                           `yaml:"base_url,omitempty"`
	Timeout              time.Duration                    `yaml:"timeout"`
	ContextWindowReserve float64                          `yaml:"context_window_reserve,omitempty"`
	ModelProfiles        map[string]LLMModelProfileConfig `yaml:"model_profiles,omitempty"`
	// Corrections toggles + per-model-profile-override the
	// provider-correction layer. Omitted = enabled (production
	// default). See `LLMCorrectionsConfig` for the wire shape.
	Corrections LLMCorrectionsConfig `yaml:"corrections,omitempty"`

	// CustomProviders is the registry of operator-declared
	// OpenAI-compatible providers. Each entry adds a new
	// `ModelProvider` to the bifrost account so operators can wire
	// NIM, vLLM, ollama, lm-studio, in-house gateways, or any other
	// OpenAI-compatible endpoint via yaml without per-provider Go
	// code. When `LLMConfig.Provider` matches a custom-provider
	// `Name`, the entry's `BaseURL` / `APIKeyEnvVar` / `Models` /
	// network knobs apply (the legacy single-provider fields
	// `APIKey` / `BaseURL` / `Timeout` are ignored for that case).
	CustomProviders []LLMCustomProviderConfig `yaml:"custom_providers,omitempty"`

	// NetworkDefaults applies to every provider (native + custom)
	// when the per-provider override is absent. Zero-valued fields
	// fall through to bifrost's package-level defaults (a
	// unification of timeout/retry knobs that were previously
	// scattered). Restart-required.
	NetworkDefaults LLMNetworkDefaults `yaml:"network_defaults,omitempty"`

	// CredentialSource selects WHERE the PRIMARY provider's API key is
	// sourced from — the inference-plane credential-source seam:
	//
	//   - "" / "local" (default) — the key resolves from `api_key` (an
	//     `env.NAME` reference or a literal) once at boot, exactly as
	//     today. The process environment is the custodian.
	//   - "remote" — the runtime PULLS the key from the coordinator's
	//     boot-declared inference broker named by `inference_broker`, at
	//     connect + refresh (never on the per-call hot path). The
	//     coordinator remains sole custodian; nothing is persisted.
	//
	// Brokered XOR local, validated LOUD at boot: `remote` REQUIRES a
	// non-empty `inference_broker` (resolving to a declared broker) and
	// REJECTS a set `api_key` (both set is a config error); a local source
	// REJECTS a set `inference_broker` (neither a broker nor a key is also
	// an error — a provider must declare exactly one source). Restart-
	// required; NOT a Protocol surface.
	CredentialSource string `yaml:"credential_source,omitempty"`

	// InferenceBroker names the boot-declared `inference_brokers[]` entry
	// the primary provider's key is pulled from when `credential_source`
	// is "remote". Referenced by NON-SECRET name — the pull endpoint /
	// audience / scope ceiling live on the named broker, never here and
	// never on the wire (the credential-plane invariant). Required
	// when `credential_source: remote`, rejected otherwise.
	InferenceBroker string `yaml:"inference_broker,omitempty"`

	// InferenceBrokers is the boot-declared list of NAMED inference-plane
	// credential brokers — the pinned credential SINK for a runtime's LLM
	// provider key. The credential-plane invariant (no admin-writable field
	// determines a credential sink) keeps every sink-determining value here,
	// referenced by non-secret name from `credential_source: remote` (and
	// from the `agent_config.set_llm_provider` Protocol write's zero-URL
	// descriptor). Config/file-only, restart-required — NOT a Protocol
	// surface.
	InferenceBrokers []InferenceBrokerConfig `yaml:"inference_brokers,omitempty"`
}

type LLMCorrectionsConfig struct {
	Enabled *bool `yaml:"enabled,omitempty"`
}

type LLMCorrectionsProfileConfig struct {
	MessageOrdering        string `yaml:"message_ordering,omitempty"`
	SchemaMode             string `yaml:"schema_mode,omitempty"`
	ReasoningEffortRouting string `yaml:"reasoning_effort_routing,omitempty"`
	ResponseFormatShape    string `yaml:"response_format_shape,omitempty"`
	UsageBackfillEnabled   bool   `yaml:"usage_backfill_enabled,omitempty"`
}

type LLMCostOverridesConfig struct {
	InputPer1M     float64 `yaml:"input_per_1m_tokens"`
	OutputPer1M    float64 `yaml:"output_per_1m_tokens"`
	ReasoningPer1M float64 `yaml:"reasoning_per_1m_tokens,omitempty"`
	Currency       string  `yaml:"currency,omitempty"`
}

type LLMCustomProviderConfig struct {
	Name                 string            `yaml:"name"`
	BaseURL              string            `yaml:"base_url"`
	APIKeyEnvVar         string            `yaml:"api_key_env_var"`
	Models               []string          `yaml:"models"`
	BaseProviderType     string            `yaml:"base_provider_type,omitempty"`
	Timeout              time.Duration     `yaml:"timeout,omitempty"`
	MaxRetries           int               `yaml:"max_retries,omitempty"`
	RetryBackoffInitial  time.Duration     `yaml:"retry_backoff_initial,omitempty"`
	RetryBackoffMax      time.Duration     `yaml:"retry_backoff_max,omitempty"`
	Concurrency          int               `yaml:"concurrency,omitempty"`
	BufferSize           int               `yaml:"buffer_size,omitempty"`
	RequestPathOverrides map[string]string `yaml:"request_path_overrides,omitempty"`
}

type LLMModelProfileConfig struct {
	ContextWindowTokens int                     `yaml:"context_window_tokens"`
	TokenEstimator      string                  `yaml:"token_estimator,omitempty"`
	JSONSchemaMode      string                  `yaml:"json_schema_mode,omitempty"`
	DefaultMaxTokens    *int                    `yaml:"default_max_tokens,omitempty"`
	ReasoningEffort     string                  `yaml:"reasoning_effort,omitempty"`
	CostOverrides       *LLMCostOverridesConfig `yaml:"cost_overrides,omitempty"`
	// Corrections — per-model overrides for the correction
	// layer. nil → use the per-provider defaults baked into
	// `internal/llm/corrections.defaultProfileFor`. See
	// `LLMCorrectionsProfileConfig` for the wire shape.
	Corrections *LLMCorrectionsProfileConfig `yaml:"corrections,omitempty"`
	// MaxRetries — caps the validator-driven retry loop the
	// `internal/llm/retry` wrapper runs against this model. Zero (the
	// default) maps to `llm.DefaultMaxRetries` (1). Negative is
	// rejected by `validateLLM`.
	MaxRetries int `yaml:"max_retries,omitempty"`
}

type LLMNetworkDefaults struct {
	Timeout             time.Duration `yaml:"timeout,omitempty"`
	MaxRetries          int           `yaml:"max_retries,omitempty"`
	RetryBackoffInitial time.Duration `yaml:"retry_backoff_initial,omitempty"`
	RetryBackoffMax     time.Duration `yaml:"retry_backoff_max,omitempty"`
	Concurrency         int           `yaml:"concurrency,omitempty"`
	BufferSize          int           `yaml:"buffer_size,omitempty"`
}

type LoadOption func(*loadConfig)

type MCPAddConnectionConfig struct {
	// StdioAllowlist is the exact set of permitted stdio command binaries /
	// paths (matched on argv[0]). Empty rejects every stdio add.
	StdioAllowlist []string `yaml:"stdio_allowlist,omitempty"`
}

type MCPAppHostConfig struct {
	DisplayModes []string `yaml:"display_modes,omitempty"`
}

type MCPCredentialInjectionConfig struct {
	// Provider names the declared `tools.oauth_providers[]` broker entry the
	// per-user credential is pulled from (the SAME registry `oauth_provider`
	// resolves against). Required; an unknown name fails validation.
	Provider string `yaml:"provider"`
	// Form selects the injection form: "header" / "basic" / "meta". Required.
	Form string `yaml:"form"`
	// Header is the target request header NAME for Form=="header" (e.g.
	// `x-vendor-api-key`). Required for that form; must be a redaction-covered
	// credential key and must not be `Authorization` (use Form=="basic").
	Header string `yaml:"header,omitempty"`
	// BasicUsername is the username half for Form=="basic". The pulled
	// credential becomes the password half: `Authorization: Basic
	// base64(BasicUsername ":" <pulled>)`. Optional — an empty username
	// (base64(":"+cred)) is the common API-key-as-basic shape. Non-secret.
	BasicUsername string `yaml:"basic_username,omitempty"`
	// MetaKey is the target `_meta` key PATH for Form=="meta", dot-separated
	// for nesting (e.g. `vendor.api_key`). Required for that form; no path
	// segment may be a reserved `_meta` key (the isolation triple / agent_id /
	// trace-context / spec namespace) and the leaf segment must be a
	// redaction-covered credential key.
	MetaKey string `yaml:"meta_key,omitempty"`
}

type MCPServerConfig struct {
	Name          string            `yaml:"name"`
	TransportMode string            `yaml:"transport_mode"`
	URL           string            `yaml:"url,omitempty"`
	Command       []string          `yaml:"command,omitempty"`
	Headers       map[string]string `yaml:"headers,omitempty" secret:"true"`
	KeepAlive     time.Duration     `yaml:"keep_alive,omitempty"`
	// Policy is the per-server default tool reliability policy.
	// Optional; nil preserves today's behaviour exactly
	// (every tool inherits `tools.DefaultPolicy()` — 30 s per-attempt
	// deadline / 4 total attempts). When set, it projects to the
	// `mcpdrv.Config.DefaultPolicy` applied to every tool this server
	// registers. Per-field zero values fall through to
	// `tools.DefaultPolicy()` (see `ToolPolicyConfig`). Restart-required.
	Policy *ToolPolicyConfig `yaml:"policy,omitempty"`
	// ToolPolicies are per-tool overrides keyed by the MCP tool's name
	// (the server-side name, NOT the `<source>_<tool>` Harbor-facing
	// name). A tool named here uses the override instead of `Policy`
	// (or the package default). Optional; empty preserves today's
	// behaviour. Restart-required.
	ToolPolicies map[string]ToolPolicyConfig `yaml:"tool_policies,omitempty"`
	// OAuthProvider names a declared `tools.oauth_providers[]` entry to
	// bind for per-identity southbound OAuth: every identity-stamped
	// per-call RPC to this server resolves a fresh bearer for the calling
	// identity and injects `Authorization: Bearer <tok>`. The value is a
	// NON-SECRET provider NAME — it selects a config-declared acquisition
	// strategy; the secret stays env-indirected on the provider entry.
	// Optional; empty leaves the connection on its static `headers`.
	// Validation rejects an unknown name, a binding on any connection
	// without an http(s) `url` — explicit stdio AND an omitted/auto
	// transport with only a `command`, which would auto-select stdio and
	// silently never inject — and a static `Authorization` header
	// alongside a binding (one auth mode per connection). Restart-required.
	OAuthProvider string `yaml:"oauth_provider,omitempty"`
	// MetaAnnotations is a static, NON-SECRET set of operator-declared
	// key/values merged verbatim into the MCP `_meta` map on every
	// identity-stamped per-call RPC — the deployment's own attribution
	// vocabulary, passed to the server as-is. Reserved keys (`tenant`,
	// `user`, `session`, `agent_id`, `traceparent`, `tracestate`, and any
	// `io.modelcontextprotocol/`-prefixed key) and empty keys are rejected
	// at validation. Optional. Restart-required.
	MetaAnnotations map[string]string `yaml:"meta_annotations,omitempty"`
	// OAuthDiscoveryAllowedOrigins is the explicit per-connection allowance
	// list for OAuth-requirement discovery cross-origin metadata fetches
	// When an MCP HTTP server advertises an OAuth requirement (a
	// `401` + `WWW-Authenticate` step-up), Harbor DISCOVERS the RFC 9728 →
	// RFC 8414 metadata chain and surfaces it as inert data; the
	// authorization-server hop is inherently cross-origin and is fetched only
	// when its origin (scheme://host[:port]) is listed here. Harbor never runs
	// the OAuth flow, never holds a token, and never dials a discovered
	// endpoint — the metadata is a report an operator confirms. Each entry
	// must be a public https origin; the runtime additionally refuses
	// private-range / IP-literal destinations at fetch time. Optional; empty
	// means no cross-origin metadata fetch is permitted (the AS half of the
	// chain surfaces as needs-allowance). Restart-required.
	OAuthDiscoveryAllowedOrigins []string `yaml:"oauth_discovery_allowed_origins,omitempty"`

	// ToolOAuthProviders are per-tool `oauth_provider` overrides keyed by the
	// MCP tool's server-side name (mirroring ToolPolicies' shape). A tool
	// named here binds THAT declared provider for its CallTool RPCs only; an
	// unlisted tool falls back to OAuthProvider (the connection-level
	// binding), and the resource / prompt paths always resolve OAuthProvider.
	// Each entry re-enforces every rule OAuthProvider does (unknown name /
	// stdio transport / static-Authorization conflict / downstream-host
	// allow-list). It closes the one-audience-per-server constraint for a
	// shared MCP server fronting N downstream resources. Boot-declared,
	// config/file-only — never a Protocol-writable field (the credential-plane
	// invariant). Optional; empty preserves today's behaviour.
	// Restart-required.
	ToolOAuthProviders map[string]string `yaml:"tool_oauth_providers,omitempty"`

	// Injection, when set, binds this connection to per-user credential
	// INJECTION for a RECEIVER-STYLE MCP server — one that authenticates by
	// RECEIVING its credential directly on each request (an arbitrary header,
	// an `Authorization: Basic` value, or a `_meta` key) instead of PULLING it
	// via RFC 8693. On every identity-stamped outbound tool call the runtime
	// SOURCES the acting principal's credential from the named broker (the SAME
	// per-user broker-pull `oauth_provider` performs — per-user via the ctx
	// identity, fetched-not-held, memory-only TTL) and INJECTS it into the
	// request per the declared, NON-SECRET mapping. Only the pulled value is
	// secret; the mapping (which broker + which target key/form) is config.
	// Mutually exclusive with OAuthProvider / ToolOAuthProviders / a static
	// `Authorization` header (one auth mode per connection) — the same
	// downstream-sink allow-list the bearer binding enforces applies here (the
	// pulled credential may only reach a boot-declared sink). Optional; empty
	// preserves today's behaviour. Restart-required.
	Injection *MCPCredentialInjectionConfig `yaml:"injection,omitempty"`
}

type MemoryConfig struct {
	Driver             string `yaml:"driver"`
	DSN                string `yaml:"dsn,omitempty" secret:"true"`
	Strategy           string `yaml:"strategy,omitempty"`
	BudgetTokens       int    `yaml:"budget_tokens,omitempty"`
	RecoveryBacklogMax int    `yaml:"recovery_backlog_max,omitempty"`
	// RecentTurns is the verbatim recent-window size for the
	// `rolling_summary` strategy. 0 → strategy default (FullZoneTurns).
	RecentTurns int `yaml:"recent_turns,omitempty"`

	// Summarizer tunes the `rolling_summary` compaction LLM: a
	// switchable model and an append-only prompt extension. Ignored by
	// the `none` and `truncation` strategies (which run no summariser).
	Summarizer MemorySummarizerConfig `yaml:"summarizer,omitempty"`

	// Retrieval is the opt-in retrieval mode. Empty (the default)
	// keeps the strategy-shaped retrieval unchanged; `"semantic"`
	// additionally embeds turns and serves similarity search
	// (`MemoryStore.SearchTurns`), COMPOSING with the configured
	// strategy — it never replaces `rolling_summary`. Requires the
	// `embeddings` block (validated; no stub fallback).
	Retrieval string `yaml:"retrieval,omitempty"`
	// RetrievalTopK caps how many scored turns a semantic
	// `SearchTurns` returns when the caller passes no limit. 0 uses
	// the memory subsystem default (5). Ignored unless
	// `retrieval: semantic`.
	RetrievalTopK int `yaml:"retrieval_top_k,omitempty"`
	// RetrievalMinScore is the cosine-similarity floor for semantic
	// recall: a scored turn must meet or exceed this value to be
	// injected into the prompt. Valid range [-1, 1]. Default 0.0
	// (turns with negative similarity, i.e. anti-correlated with the
	// query, are filtered out while marginally-similar turns are
	// admitted). Ignored unless `retrieval: semantic`.
	RetrievalMinScore float64 `yaml:"retrieval_min_score,omitempty"`
}

type MemorySummarizerConfig struct {
	Model  string `yaml:"model,omitempty"`  // "" → main LLM default model
	Prompt string `yaml:"prompt,omitempty"` // "" → baseline only; else appended to the baseline summariser prompt
}

type MultimodalConfig struct {
	Disposition map[string]string `yaml:"disposition,omitempty"`
}

type PauseResumeConfig struct {
	MaxParkDuration time.Duration `yaml:"max_park_duration"`
	SweepInterval   time.Duration `yaml:"sweep_interval"`
}

type PlannerConfig struct {
	Driver                 string                  `yaml:"driver,omitempty"`
	MaxSteps               int                     `yaml:"max_steps,omitempty"`
	ExtraGuidance          string                  `yaml:"extra_guidance,omitempty"`
	ReasoningReplay        string                  `yaml:"reasoning_replay,omitempty"`
	MaxToolExamplesPerTool int                     `yaml:"max_tool_examples_per_tool,omitempty"`
	ParallelToolCalls      *bool                   `yaml:"parallel_tool_calls,omitempty"`
	SkillsContextMax       int                     `yaml:"skills_context_max,omitempty"`
	AbsoluteMaxSpawnDepth  int                     `yaml:"absolute_max_spawn_depth,omitempty"`
	MaxBatchSpawns         int                     `yaml:"max_batch_spawns,omitempty"`
	TokenBudget            int                     `yaml:"token_budget,omitempty"`
	PlanningHints          PlannerPlanningHintsCfg `yaml:"planning_hints,omitempty"`
	Extra                  map[string]string       `yaml:"extra,omitempty"`
}

type PlannerPlanningHintsCfg struct {
	// Constraints is free-form text rendered verbatim into the
	// `<planning_constraints>` section. Voice/tone rules, hard
	// negative-space guidance ("never call X without prior approval"),
	// or domain-specific constraints. Empty omits the line.
	Constraints string `yaml:"constraints,omitempty"`
	// PreferredTools lists tool names the planner should prefer when
	// multiple satisfy the same goal. Empty omits the line.
	PreferredTools []string `yaml:"preferred_tools,omitempty"`
}

type ProjectedToolPolicy struct {
	// TimeoutMS is the per-attempt deadline in milliseconds; 0 means
	// "inherit the default" at the runtime layer.
	TimeoutMS int
	// MaxRetries is `max_attempts - 1` when `max_attempts >= 1`, else
	// 0 (inherit the default total attempt count).
	MaxRetries int
	// BackoffBase / BackoffMax are the projected backoff base / cap; a
	// zero Duration inherits the default.
	BackoffBase time.Duration
	BackoffMax  time.Duration
	// BackoffMult is the per-retry multiplier; 0 inherits the default.
	BackoffMult float64
	// RetryOn carries the validated error-class strings (`transient` /
	// `timeout` / `5xx` / `permanent`). nil/empty inherits the default
	// allowlist. The strings are validated against the allowlist by
	// ToToolPolicy; the runtime copy turns them into `tools.ErrorClass`.
	RetryOn []string
	// RetryOnEmpty, when true, instructs the runtime copy to build an
	// EXPLICIT empty (non-nil) `RetryOn` slice — the policy shell reads
	// that as "retry on nothing" (exactly one attempt). Set by
	// ToToolPolicy when `max_attempts == 1` and the operator named no
	// `retry_on` allowlist; see the comment in ToToolPolicy for why the
	// MaxRetries:0 fall-through alone is insufficient. Mutually
	// exclusive with a populated RetryOn.
	RetryOnEmpty bool
}

type ProtocolConfig struct {
	MaxRequestBytes int `yaml:"max_request_bytes,omitempty"`
}

type RunCompletionHookConfig struct {
	// Tool is the catalog tool name the transcript is dispatched to. Empty
	// disables the static hook. The tool need not be exposed to the planner —
	// the executor resolves it against the full catalog.
	Tool string `yaml:"tool,omitempty"`
	// Timeout bounds the detached hook dispatch. Non-positive falls back to
	// the runtime default (10s) at run start.
	Timeout time.Duration `yaml:"timeout,omitempty"`
}

type RuntimeConfig struct {
	// Hooks configures the runtime's run-lifecycle hooks. The only hook
	// point today is the run-completion hook (`runtime.hooks.run_completion`).
	Hooks RuntimeHooksConfig `yaml:"hooks,omitempty"`
	// Naming is the fleet-default session auto-naming policy
	// (`runtime.naming`). Opt-in, default off: with the block absent (or
	// `auto: false`) the runtime does no auto-naming. A per-agent
	// agent-config `naming` section overrides this default at run start.
	Naming RuntimeNamingConfig `yaml:"naming,omitempty"`
}

type RuntimeHooksConfig struct {
	// RunCompletion configures the run-completion hook: at the run loop's
	// terminal boundary the runtime dispatches the run's transcript to the
	// named catalog tool. Empty `Tool` disables the static hook (the
	// versioned agent-config `hooks` section can still enable it per agent).
	RunCompletion RunCompletionHookConfig `yaml:"run_completion,omitempty"`
}

type RuntimeNamingConfig struct {
	// Auto enables session auto-naming fleet-wide (false = off).
	Auto bool `yaml:"auto,omitempty"`
	// AfterTurns is the completed-run count at which the first auto-name
	// fires. Zero defaults to 1 at run start; negative is rejected.
	AfterTurns int `yaml:"after_turns,omitempty"`
	// RepeatEvery, when > 0, re-names every N completed turns after the
	// first; 0 names once only. Negative is rejected.
	RepeatEvery int `yaml:"repeat_every,omitempty"`
	// MaxRepetitions caps the TOTAL auto-namings (including the first);
	// required >= 1 when RepeatEvery > 0 (no unlimited value exists).
	MaxRepetitions int `yaml:"max_repetitions,omitempty"`
	// MaxTitleLen bounds the auto title in runes. Zero defaults to 80 at run
	// start; a set value must be in [8, 200].
	MaxTitleLen int `yaml:"max_title_len,omitempty"`
	// Model, when set, is the model the auto-naming call requests (empty =
	// the run's effective model). Validated against ModelProfiles at boot.
	Model string `yaml:"model,omitempty"`
}

type ServerConfig struct {
	BindAddr            string        `yaml:"bind_addr"`
	ShutdownGracePeriod time.Duration `yaml:"shutdown_grace_period"`
	AllowedOrigins      []string      `yaml:"allowed_origins,omitempty"`
	CORSDevAllowAny     bool          `yaml:"cors_dev_allow_any,omitempty"`
	// DebugAddr optionally enables the pprof debug HTTP listener on a
	// SEPARATE host:port (never the Protocol mux). Empty (the default)
	// disables it entirely. When set it MUST be a loopback address
	// (127.0.0.0/8 or ::1) — the validator rejects any other host so the
	// profiler surface can never be exposed off-box. The listener serves
	// only net/http/pprof handlers and is off by default; it is a
	// dev/diagnostic escape hatch, not a production surface.
	DebugAddr string `yaml:"debug_addr,omitempty"`
}

type SessionsConfig struct {
	IdleTTL       time.Duration `yaml:"idle_ttl"`
	HardCap       time.Duration `yaml:"hard_cap"`
	SweepInterval time.Duration `yaml:"sweep_interval"`
}

type SkillsConfig struct {
	Driver    string                `yaml:"driver,omitempty"`
	DSN       string                `yaml:"dsn,omitempty" secret:"true"`
	Directory SkillsDirectoryConfig `yaml:"directory,omitempty"`

	// Retrieval is the opt-in retrieval mode for `Search` /
	// `skill_search`. Empty (the default) keeps the token-savvy
	// FTS5 → regex → exact ladder; `"semantic"` ranks by embedding
	// similarity over the identity-scoped catalog instead (result
	// path `"semantic"`). Requires the `embeddings` block (validated;
	// no stub fallback). Capability filtering, redaction, and the
	// budgeter apply unchanged on top.
	Retrieval string `yaml:"retrieval,omitempty"`
}

type SkillsDirectoryConfig struct {
	Pinned     []string `yaml:"pinned,omitempty"`
	MaxEntries int      `yaml:"max_entries,omitempty"`
	Selection  string   `yaml:"selection,omitempty"`
}

type StateConfig struct {
	Driver string `yaml:"driver"`
	DSN    string `yaml:"dsn,omitempty" secret:"true"`
}

type TasksConfig struct {
	Driver               string        `yaml:"driver"`
	RetainTurnTimeout    time.Duration `yaml:"retain_turn_timeout"`
	ContinuationHopLimit int           `yaml:"continuation_hop_limit"`
}

type TelemetryConfig struct {
	LogFormat    string `yaml:"log_format"`
	LogLevel     string `yaml:"log_level"`
	OTelEndpoint string `yaml:"otel_endpoint,omitempty"`
	ServiceName  string `yaml:"service_name"`
}

type ToolApprovalConfig struct {
	// Policy names which bundled approval policy to apply. The
	// catalog builder maps this name onto a concrete
	// `approval.ApprovalPolicy` instance. Allowed values:
	//   - "deny-all"      → `approval.AlwaysDenyPolicy`
	//   - "approve-all"   → `approval.AlwaysApprovePolicy` (dev only)
	//   - "tagged"        → `approval.TaggedPolicy` (consults
	//                       `RequireTags` below)
	// An unknown policy value fails the catalog build with a wrapped
	// error naming the offending value.
	Policy string `yaml:"policy"`
	// Reason is the operator-facing classification carried on
	// `tool.approval_requested`. Optional — the bundled policies
	// supply a sensible default.
	Reason string `yaml:"reason,omitempty"`
	// RequireTags is consulted by the `tagged` policy. An entry whose
	// `Policy: tagged` AND `RequireTags: []` is rejected — the
	// tagged policy with no tags is a no-op (configuration smell).
	RequireTags []string `yaml:"require_tags,omitempty"`
}

type ToolEntryConfig struct {
	// Name is the catalog tool name the entry applies to. Required.
	// The catalog builder fails closed when no tool registered with
	// this name resolves at boot.
	Name string `yaml:"name"`
	// LoadingMode controls when this tool appears in the planner's
	// prompt-time catalog. "" or "always" = every turn (default).
	// "deferred" = hidden by default; the LLM discovers via meta-tools.
	LoadingMode string `yaml:"loading_mode,omitempty"`
	// Approval declares an approval-gate wiring for this tool. Omit
	// for tools that need no gating. When present, `Approval.Policy`
	// MUST be one of the canonical policy names; an unknown value
	// fails closed.
	Approval *ToolApprovalConfig `yaml:"approval,omitempty"`
	// OAuth declares an OAuth binding for this tool. Omit for tools
	// that need no OAuth. When present, `OAuth.Provider` MUST name a
	// configured OAuth source and `OAuth.BindingScope` MUST be one of
	// "user" / "agent".
	OAuth *ToolOAuthConfig `yaml:"oauth,omitempty"`
}

type ToolOAuthConfig struct {
	// Provider names the OAuth source the tool binds to. The catalog
	// builder consults the configured OAuth registry; a name that
	// resolves to no source fails the catalog build loud.
	Provider string `yaml:"provider"`
	// BindingScope is "user" or "agent". An
	// invalid value fails the catalog build with a wrapped error
	// naming the offending value.
	BindingScope string `yaml:"binding_scope"`
}

type ToolOAuthCredentialBrokerConfig struct {
	// Name is the operator-facing broker identifier (unique within the
	// slice; referenced by name from a Protocol-installed provider
	// descriptor). Required.
	Name string `yaml:"name"`
	// TokenURL is the broker's RFC-8693 token-exchange endpoint — the
	// credential sink the org's client_id / client_secret are POSTed to.
	// Required; must be https (or a loopback host for the dev/fixture
	// case). Boot-pinned: never wire-writable.
	TokenURL string `yaml:"token_url"`
	// AllowedDownstreamHosts is the sink allow-list for the exchanged
	// bearer. Required non-empty (a bearer-minting broker must declare
	// where its tokens may be injected).
	AllowedDownstreamHosts []string `yaml:"allowed_downstream_hosts"`
	// AuthTokenEnv names the env var holding the runtime's own broker
	// credential (§7 rule 2 — never hardcoded). Required non-empty. It is the
	// `Authorization: Bearer` the runtime presents to CredentialURL when it
	// pulls the org client credential the exchange POSTs to TokenURL.
	AuthTokenEnv string `yaml:"auth_token_env"`
	// CredentialURL is the boot-pinned coordinator credential endpoint the
	// runtime pulls its OWN org client credential (client_id / client_secret)
	// from — the `remote` credential-source PULL URL for a
	// Protocol-installed broker-pull provider. It is a credential-sink-adjacent
	// value (it authenticates with AuthTokenEnv and yields the org secret the
	// exchange POSTs), so it is BOOT-PINNED, config/file-only, never
	// wire-writable (the credential-plane invariant). Required (https,
	// or a loopback host for the dev/fixture case) for any broker referenced by
	// a Protocol-installed provider — validated loud when the broker is resolved
	// at install time. Distinct from TokenURL: CredentialURL is the GET the
	// runtime pulls its client credential from; TokenURL is the POST the
	// exchange sends it to.
	CredentialURL string `yaml:"credential_url,omitempty"`
	// Audience is the boot-pinned token-audience ceiling for the exchanged
	// downstream token — the authority for the exchanged token's audience,
	// decoupled from the caller-chosen provider name (closing the
	// audience-picking lever). Empty preserves the legacy
	// audience-from-name behaviour. Boot-pinned, never wire-writable.
	Audience string `yaml:"audience,omitempty"`
	// ScopeCeiling is the boot-pinned scope ceiling for the exchanged token.
	// When non-empty the SCOPES an installed descriptor requests are
	// INTERSECTED against it — a requested scope outside the ceiling is dropped,
	// never honoured (so an installed descriptor can never widen scope past the
	// boot ceiling). Empty preserves the legacy pass-through. Boot-pinned,
	// never wire-writable.
	ScopeCeiling []string `yaml:"scope_ceiling,omitempty"`
	// CacheTTL caps the in-memory serve horizon for a brokered token.
	// Optional; zero = driver default.
	CacheTTL time.Duration `yaml:"cache_ttl,omitempty"`
	// Timeout bounds a single broker exchange. Optional; zero = driver
	// default.
	Timeout time.Duration `yaml:"timeout,omitempty"`
}

type ToolOAuthProviderConfig struct {
	Name   string `yaml:"name"`
	Driver string `yaml:"driver"`
	// CredentialSource selects the §4.4 seam through which this
	// provider's OWN client credential resolves:
	//   - "" / "env" — resolved from ClientIDEnv / ClientSecretEnv once
	//     at boot (the default; existing configs are byte-compatible).
	//   - "remote" — pulled from a coordinator endpoint (the Remote
	//     block) at first need. Valid only for the "tokenexchange"
	//     driver. Declaring "remote" alongside ClientIDEnv /
	//     ClientSecretEnv is a validation error (one source, no dual
	//     path).
	CredentialSource string `yaml:"credential_source,omitempty"`
	ClientIDEnv      string `yaml:"client_id_env,omitempty"`
	ClientSecretEnv  string `yaml:"client_secret_env,omitempty"`
	// Remote carries the coordinator-served credential-fetch parameters;
	// required when CredentialSource == "remote", rejected otherwise.
	Remote      *ToolOAuthRemoteConfig `yaml:"remote,omitempty"`
	Scopes      []string               `yaml:"scopes,omitempty"`
	AuthURL     string                 `yaml:"auth_url,omitempty"`
	TokenURL    string                 `yaml:"token_url,omitempty"`
	RedirectURL string                 `yaml:"redirect_url,omitempty"`
	Extra       map[string]string      `yaml:"extra,omitempty"`

	// AllowedDownstreamHosts is the boot-declared set of downstream
	// connection hosts (host[:port]) a southbound MCP binding may inject
	// this provider's credential into (the exchanged bearer for the
	// `tokenexchange` driver; the interactive bearer for `oauth2`). It is
	// the credential-sink allow-list: the credential-plane invariant is
	// that no admin-writable field determines a credential sink, so the
	// sink set is boot-declared and config/file-only. A binding whose MCP
	// connection host is not listed is refused at attach, fail-closed —
	// never a silent unauthenticated dial. Host comparison normalises
	// host[:port] (default-port equivalence; case-insensitive) via
	// [NormalizeDownstreamHost].
	//
	// MANDATORY (non-empty) for any provider a `tools.mcp_servers[]`
	// connection binds: a provider that can inject a bearer must declare
	// where. This is a behaviour change for an existing OAuth-bound
	// connection that never listed its downstream host (see the CHANGELOG
	// migration note) — the empty-list rejection surfaces at boot, not at
	// first call. Restart-required.
	AllowedDownstreamHosts []string `yaml:"allowed_downstream_hosts,omitempty"`

	// Audience is the boot-declared token-audience ceiling for the
	// `tokenexchange` driver. When non-empty it is the authority for the
	// exchanged token's audience — decoupled from the caller-chosen
	// provider name — closing the audience-picking lever. Empty preserves
	// the legacy audience-from-name behaviour (opt-in hardening;
	// backward-compatible). Ignored by the interactive `oauth2` driver.
	// Restart-required.
	Audience string `yaml:"audience,omitempty"`

	// ScopeCeiling is the boot-declared scope ceiling for the
	// `tokenexchange` driver. When non-empty the requested `Scopes` are
	// INTERSECTED against it — a requested scope outside the ceiling is
	// dropped, never honoured. Empty preserves the legacy pass-through.
	// Ignored by the interactive `oauth2` driver. Restart-required.
	ScopeCeiling []string `yaml:"scope_ceiling,omitempty"`

	// ResourceIndicator is the boot-declared RFC 8707 `resource` value the
	// `tokenexchange` driver carries as the `resource` form parameter on
	// every exchange request (the audience the exchanged token is bound to).
	// A JWT-shaped returned token whose `aud` claim excludes this value fails
	// the exchange loud (never cached). Empty preserves today's behaviour (no
	// `resource` parameter sent). NEVER auto-populated from discovery
	// (discovery is report-only; an operator copies a discovered+confirmed
	// value in by hand). Ignored by the interactive `oauth2` driver.
	// Restart-required.
	ResourceIndicator string `yaml:"resource_indicator,omitempty"`

	// IncludeActorToken opts a `tokenexchange` provider into carrying the
	// run's verified acting principal (`agent_id`, when present on ctx) as an
	// RFC 8693 `actor_token` on the exchange. Default false; an absent
	// `agent_id` sends no `actor_token` regardless (a byte-identical request
	// to today). The actor token is the runtime's VERIFIED acting principal —
	// never a client-supplied field. Ignored by the interactive `oauth2`
	// driver. Restart-required.
	//
	// Caching note: the exchanged token is cached at user granularity
	// (scope, tenant, user, source) — the acting principal is deliberately
	// NOT part of the cache key, because `agent_id` is not an isolation
	// principal. Within one cached token's TTL, a second acting principal
	// under the same (tenant, user) reuses the token minted under the
	// first — no isolation boundary is crossed (the token stays user-bound
	// and the `actor_asserted` audit signal fires only on the real
	// exchange). If a downstream broker scopes grants PER acting principal,
	// disable caching pressure by narrowing the token TTL rather than
	// expecting per-actor cache separation here.
	IncludeActorToken bool `yaml:"include_actor_token,omitempty"`

	// AllowPrivateTokenURL is a DEV-ONLY opt-in that permits the
	// `tokenexchange` driver's credential-bearing exchange POST to dial a
	// PRIVATE-range / link-local resolved address for THIS provider's own
	// `token_url` — the standard containerized local-dev topology, where the
	// broker (a coordinator) sits behind a private-IP TLS sidecar. It
	// RELAXES a load-bearing DNS-rebinding dial guard, so it is default
	// false / fail-closed: with it unset the guard refuses any resolved
	// private / link-local / ULA address. When set it relaxes ONLY that
	// branch, scoped to this provider's own boot-declared `token_url`; the
	// unspecified-address (0.0.0.0 / ::) block, the loopback carve-out
	// (loopback stays allowed either way), and the redirect refusal are
	// UNCHANGED. Boot-declared and config/file-only — never Protocol-writable
	// or derived from a discovered / wire descriptor. The same opt-in is
	// also available globally via the `HARBOR_DEV_ALLOW_PRIVATE_EXCHANGE`
	// boot env; the effective posture is this flag OR that env. Ignored by
	// the interactive `oauth2` driver. Restart-required. Do NOT enable in
	// production.
	AllowPrivateTokenURL bool `yaml:"allow_private_token_url,omitempty"`
}

type ToolOAuthRemoteConfig struct {
	// URL is the coordinator credential endpoint. Required; validated
	// well-formed at boot. MUST be https — the fetch sends the runtime's
	// service bearer token, so TLS is mandatory; plaintext http is
	// accepted only for a loopback host (127.0.0.1 / ::1 / localhost —
	// the local fixture / dev case). Redirects from the endpoint are
	// refused, never followed.
	URL string `yaml:"url"`
	// AuthTokenEnv names the env var holding the runtime's own service
	// token, sent as a Bearer credential. Required; validated non-empty
	// at boot (read lazily at fetch time so a rotated token is picked up
	// without restart).
	AuthTokenEnv string `yaml:"auth_token_env"`
	// CacheTTL caps the in-memory serve horizon. Optional; zero = the
	// driver default (5m). The effective horizon is min(response
	// expires_in, CacheTTL).
	CacheTTL time.Duration `yaml:"cache_ttl,omitempty"`
	// Timeout bounds a single fetch. Optional; zero = the driver default
	// (30s).
	Timeout time.Duration `yaml:"timeout,omitempty"`
}

type ToolPolicyConfig struct {
	MaxAttempts   int      `yaml:"max_attempts,omitempty"`
	TimeoutMS     int      `yaml:"timeout_ms,omitempty"`
	RetryOn       []string `yaml:"retry_on,omitempty"`
	BackoffBaseMS int      `yaml:"backoff_base_ms,omitempty"`
	BackoffMult   float64  `yaml:"backoff_mult,omitempty"`
	BackoffMaxMS  int      `yaml:"backoff_max_ms,omitempty"`
}

type ToolsConfig struct {
	HTTPManifests    []string                  `yaml:"http_manifests,omitempty"`
	MCPServers       []MCPServerConfig         `yaml:"mcp_servers,omitempty"`
	A2APeers         []A2APeerConfig           `yaml:"a2a_peers,omitempty"`
	Entries          []ToolEntryConfig         `yaml:"entries,omitempty"`
	OAuthProviders   []ToolOAuthProviderConfig `yaml:"oauth_providers,omitempty"`
	OAuthTokenKEKEnv string                    `yaml:"oauth_token_kek_env,omitempty"`

	// OAuthCredentialBrokers is the boot-declared list of NAMED credential
	// sinks (token endpoint + allowed downstream hosts + broker
	// credential env). It is the config home for the pinned sinks a
	// Protocol-installed, zero-URL provider descriptor references by name
	// — the credential-plane invariant keeps every sink-determining value
	// boot-declared, config/file-only. Additive; the inline
	// `oauth_providers[].remote` block stays valid. Restart-required.
	//
	// This list is boot-validated but has no runtime consumer yet: the
	// Protocol surface that resolves a provider descriptor's
	// `credential_broker` against it lands alongside it in the same wave.
	// Until then a declared broker is validated and inert (declaring one
	// changes no behaviour); this is the sink home landing ahead of its
	// consumer within the wave, not a dangling field.
	OAuthCredentialBrokers []ToolOAuthCredentialBrokerConfig `yaml:"oauth_credential_brokers,omitempty"`

	// AllowWireOAuthDescriptor is a DEV-ONLY, fail-closed opt-in that permits
	// `agent_config.set_oauth_provider` / `add_mcp_connection` to carry a FULL
	// OAuth-provider binding over the wire (`token_url` / `audience` / `scopes` /
	// `remote{}`) instead of only a boot-declared provider NAME — so a
	// coordinator can stand up a new OAuth-fronted MCP server at runtime without a
	// static `oauth_providers[]` block and a redeploy. It RELAXES the
	// credential-plane invariant that no admin-writable field determines a
	// credential sink, so it is default false / fail-closed: with it unset (all of
	// production), a wire descriptor carrying any credential-sink field is REJECTED
	// exactly as the zero-URL name-only binding rejects it today. When set, the
	// relaxation stays bounded — `allowed_downstream_hosts` is DERIVED from the
	// connected server's own URL (never a wire field) and the wire `token_url` /
	// `remote{}` dials face the identical token-exchange SSRF backstop. The same
	// opt-in is also available globally via the `HARBOR_ALLOW_WIRE_OAUTH_DESCRIPTOR`
	// boot env; the effective posture is this flag OR that env. Restart-required.
	// Do NOT enable in production.
	AllowWireOAuthDescriptor bool `yaml:"allow_wire_oauth_descriptor,omitempty"`

	// BuiltIn lists opt-in tools shipped in the Harbor binary that the
	// runtime should register against the catalog at boot. V1.1 ships
	// two names: `clock.now` (current UTC time) and `text.echo` (echo
	// input verbatim). The names are mirrored from
	// `internal/tools/builtin.KnownNames()` via `KnownBuiltInTools()`
	// below; a typo fails validation pre-boot rather than at runtime.
	// Empty list = no built-ins registered. Restart-required (no
	// `reload:"live"` tag).
	BuiltIn []string `yaml:"built_in,omitempty"`

	// Custom lists operator-declared custom tools whose Go shell is
	// generated by `harbor scaffold`. Each entry
	// names the tool, gives a one-line description, and declares its
	// input + output shape as a flat map of `field: type` (V1.1
	// supports `string`, `integer`, `number`, `boolean`, `[]string`).
	// The scaffolder materialises one `tools/<name>.go` stub + matching
	// `tools/<name>_test.go` per entry; the rendered Go contains the
	// typed Input/Output structs and a `Handle` stub the operator fills
	// in. The runtime does NOT auto-discover these tools — the operator
	// imports the generated `tools/` package + calls `RegisterTools`
	// from the agent's bootstrap. Restart-required (no `reload:"live"`).
	Custom []CustomToolConfig `yaml:"custom,omitempty"`

	// GrantedScopes is the operator-declared list of authorization
	// scopes the dev binary's planner-facing catalog view treats as
	// granted. The runtime catalog projects only tools whose
	// `AuthScopes` are entirely contained in this set; tools that
	// require a missing scope are invisible to the planner.
	//
	// the field closes the runloop's
	// `nil /* TODO */` hard-code that left the catalog
	// unfiltered. Empty list = no scopes granted (the existing latent
	// default — tools that declare AuthScopes are invisible). The
	// scopes are operator-defined per their tool sources; the
	// validator only asserts that each entry is a non-empty string,
	// with no allowlist.
	//
	// Restart-required (no `reload:"live"` tag — scope changes
	// trigger a re-evaluation of every catalog descriptor).
	GrantedScopes []string `yaml:"granted_scopes,omitempty"`

	// SearchCacheDSN is the SQLite DSN backing the tool
	// SearchCache (FTS5 + regex fallback). Empty means the dev binary
	// uses an in-memory cache (the V1 default — discovery state lives
	// for the process lifetime). Operators can point at an on-disk
	// path (`file:./harbor-tools.db?_pragma=...`) to persist the
	// cache across reboots. Restart-required.
	SearchCacheDSN string `yaml:"search_cache_dsn,omitempty"`

	// MCPAppHost configures the deployment-wide MCP App
	// (`io.modelcontextprotocol/ui`) host capability the runtime advertises
	// to every MCP server during the initialize handshake. The host's
	// renderable display modes do not vary per server, so this is a single
	// deployment-level block, not a per-server field. Optional; nil resolves
	// to the inline-only baseline (the mode the Console renders today).
	// Restart-required.
	MCPAppHost *MCPAppHostConfig `yaml:"mcp_app_host,omitempty"`

	// MCPAddConnection gates the admin-driven runtime add of a NEW MCP
	// server connection over the Protocol
	// (`agent_config.add_mcp_connection`). Adding a stdio server spawns an
	// operator-supplied command — an RCE surface — so it is fail-closed: a
	// stdio add is permitted ONLY when its command argv[0] is listed in
	// StdioAllowlist. An empty / nil block rejects every stdio add (the
	// secure default); http adds are admin-scoped but not gated here.
	// Optional. Restart-required.
	MCPAddConnection *MCPAddConnectionConfig `yaml:"mcp_add_connection,omitempty"`
}