agentcfg

type Config struct {
	// Driver names the registered factory. Empty → DefaultDriver.
	Driver string
}

type ConfigPayload struct {
	PromptLayers   *PromptLayers          `json:"prompt_layers,omitempty"`
	ToolExposure   *ToolExposure          `json:"tool_exposure,omitempty"`
	Skills         *SkillsSelection       `json:"skills,omitempty"`
	Connections    *ConnectionsSection    `json:"connections,omitempty"`
	OAuthProviders *OAuthProvidersSection `json:"oauth_providers,omitempty"`
	LLMParams      *LLMParams             `json:"llm_params,omitempty"`
	Hooks          *HooksSection          `json:"hooks,omitempty"`
	Naming         *NamingSection         `json:"naming,omitempty"`
}

type ConfigRevertedPayload struct {
	events.SafeSealed
	// Author is the identity that performed the rollback.
	Author identity.Quadruple
	// AgentID is the agent whose active pointer was repointed.
	AgentID string
	// RevisionID is the revision the active pointer now points to.
	RevisionID string
	// FromRevisionID is the previously-active revision id (empty when the
	// agent had no active pointer before the rollback).
	FromRevisionID string
	// OccurredAt is the rollback instant.
	OccurredAt time.Time
}

type ConfigRevisedPayload struct {
	events.SafeSealed
	// Author is the identity that wrote the revision.
	Author identity.Quadruple
	// AgentID is the agent whose config was revised (a registration
	// identity, NOT an isolation principal).
	AgentID string
	// RevisionID is the new revision's id.
	RevisionID string
	// ParentRevisionID is the revision the new one descends from (empty
	// for the first revision).
	ParentRevisionID string
	// ContentHash is the new revision's content hash (for diff/audit
	// correlation; never the content itself).
	ContentHash string
	// OccurredAt is the revision's creation instant.
	OccurredAt time.Time
}

type ConfigScope uint8

type ConnectionsDiff struct {
	// Added are the connection names present in the to-revision but not the
	// from-revision.
	Added []string
	// Removed are the connection names present in the from-revision but not
	// the to-revision.
	Removed []string
}

type ConnectionsSection struct {
	// Servers is the set of runtime-added MCP connection descriptors,
	// keyed by Name. Canonicalised sorted-by-name with a name-unique
	// invariant so a re-ordering does not perturb the content hash.
	Servers []MCPConnectionDescriptor `json:"servers,omitempty"`
}

type Deps struct {
	State state.StateStore
	Bus   events.EventBus
	Clock func() time.Time
}

type Diff struct {
	// FromRevisionID / ToRevisionID name the compared revisions.
	FromRevisionID string
	ToRevisionID   string
	// Skills is the structured set-diff of the skills membership.
	Skills SkillsDiff
	// ToolExposure is the structured set-diff of the MCP-exposure /
	// per-tool policy.
	ToolExposure ToolExposureDiff
	// PromptLayers is the text delta of the base + user prompt layers.
	PromptLayers PromptLayersDiff
	// Connections is the structured set-diff of the runtime-added MCP
	// connection descriptors (by name).
	Connections ConnectionsDiff
	// OAuthProviders is the structured set-diff of the Protocol-installed
	// OAuth-provider descriptors (by name).
	OAuthProviders OAuthProvidersDiff
	// LLMParams is the per-field delta of the per-agent LLM-parameter
	// section (model / temperature / max-tokens / reasoning-effort).
	LLMParams LLMParamsDiff
	// Hooks is the per-field delta of the run-lifecycle-hook section
	// (the run-completion hook's tool + timeout).
	Hooks HooksDiff
	// Naming is the per-field delta of the session auto-naming policy
	// section.
	Naming NamingDiff
}

type Factory func(cfg Config, deps Deps) (Registry, error)

type HooksDiff struct {
	// SectionPresentChanged reports whether the hooks-section PRESENCE differs
	// (absent vs present). A present-but-empty section (the explicit per-agent
	// no-hook) renders no tool and no timeout, so WITHOUT this dimension
	// a yaml-hook-on agent toggling to an explicit `{}` opt-out would be an
	// invisible revision in agent_config.diff (a phantom revision in the
	// Console diff view). Mirrors NamingDiff's tri-state Auto. Present renders
	// "present"; absent renders "".
	SectionPresentChanged bool
	SectionPresentFrom    string
	SectionPresentTo      string
	// RunCompletionToolChanged reports whether the hook's target tool differs.
	RunCompletionToolChanged bool
	RunCompletionToolFrom    string
	RunCompletionToolTo      string
	// RunCompletionTimeoutChanged reports whether the hook's timeout differs.
	RunCompletionTimeoutChanged bool
	RunCompletionTimeoutFrom    string
	RunCompletionTimeoutTo      string
}

type HooksSection struct {
	// RunCompletion pins the agent's run-completion hook when non-nil with a
	// non-empty tool. Nil in a PRESENT section is the explicit no-hook.
	RunCompletion *RunCompletionHook `json:"run_completion,omitempty"`
}

type LLMParams struct {
	// Model, when set, is the model the agent's next run requests
	// (overriding the tenant-wide baseline / config default). An empty
	// string normalises to unset.
	Model *string `json:"model,omitempty"`
	// Temperature, when set, is the sampling temperature for the next run.
	Temperature *float64 `json:"temperature,omitempty"`
	// MaxTokens, when set, is the per-message output-token ceiling.
	MaxTokens *int `json:"max_tokens,omitempty"`
	// ReasoningEffort, when set, is the reasoning-effort hint
	// ("off" | "low" | "medium" | "high"). An empty string normalises to
	// unset.
	ReasoningEffort *string `json:"reasoning_effort,omitempty"`
}

type LLMParamsDiff struct {
	ModelChanged bool
	ModelFrom    string
	ModelTo      string

	TemperatureChanged bool
	TemperatureFrom    string
	TemperatureTo      string

	MaxTokensChanged bool
	MaxTokensFrom    string
	MaxTokensTo      string

	ReasoningEffortChanged bool
	ReasoningEffortFrom    string
	ReasoningEffortTo      string
}

type LoadingModeChange struct {
	Key  string
	From string
	To   string
}

type MCPConnectionDescriptor struct {
	// Name is the unique MCP source id (the tool-name prefix the planner
	// sees). Required.
	Name string `json:"name"`
	// Transport is the wire transport — "stdio" or "http".
	Transport MCPTransport `json:"transport"`
	// Command is the stdio argv (argv[0] is the binary; no shell). Set for
	// the stdio transport; empty for http.
	Command []string `json:"command,omitempty"`
	// URL is the http(s) endpoint. Set for the http transport; empty for
	// stdio.
	URL string `json:"url,omitempty"`
	// OAuthProvider names a declared OAuth provider to bind for per-identity
	// southbound bearer injection on this connection's calls. NON-SECRET — a
	// provider NAME selecting a config-declared acquisition strategy; the
	// secret stays on the provider. Empty leaves the connection on its static
	// (attach-time) headers. Set only for the http transport.
	OAuthProvider string `json:"oauth_provider,omitempty"`
	// MetaAnnotations is a static, NON-SECRET set of operator-declared
	// key/values merged verbatim into the MCP `_meta` on every
	// identity-stamped per-call RPC (the deployment's attribution
	// vocabulary). Reserved / spec-prefixed keys are rejected at attach.
	MetaAnnotations map[string]string `json:"meta_annotations,omitempty"`
	// OAuthDiscoveryAllowedOrigins is the explicit per-connection cross-origin
	// allow-list of public https origins the MCP OAuth-requirement discovery
	// walker may fetch authorization-server metadata from. NON-SECRET (an origin
	// allow-list, never a secret) — it rides the revision spine (versioned /
	// diffable / rollback-able) and is writable live over
	// `agent_config.set_mcp_discovery_origins`. Empty leaves the
	// authorization-server hop needs-allowance (partial discovery), never a
	// network hole: a granted origin is still refused at dial time if it
	// resolves private / loopback. Set only for the http transport.
	OAuthDiscoveryAllowedOrigins []string `json:"oauth_discovery_allowed_origins,omitempty"`
}

type MCPConnectionLifecyclePayload struct {
	events.SafeSealed
	// Author is the identity that drove the add.
	Author identity.Quadruple
	// AgentID is the agent the connection was added to (a registration
	// identity, NOT an isolation principal).
	AgentID string
	// ServerID is the MCP source id (name) of the connection being added.
	ServerID string
	// Transport is the connection transport ("stdio" / "http") — non-secret.
	Transport string
	// State is the lifecycle state the event marks ("pending" / "online" /
	// "failed" / "auth_required").
	State string
	// RevisionID is the recording revision id (set for online / auth_required;
	// empty for pending and for a failed add, which records no revision).
	RevisionID string
	// PauseToken is the unified-pause/resume token the auth_required attach
	// parked on (set only for the auth_required state); empty otherwise. It
	// is an opaque runtime handle, NOT a credential.
	PauseToken string
	// Reason is a SAFE, operator-facing failure reason (set only for the
	// failed state); never a secret or raw transport payload.
	Reason string
	// OccurredAt is the lifecycle-transition instant.
	OccurredAt time.Time
}

type MCPConnectionPausedPayload struct {
	events.SafeSealed
	// Author is the identity that recorded the pause.
	Author identity.Quadruple
	// AgentID is the agent whose MCP exposure changed (a registration
	// identity, NOT an isolation principal).
	AgentID string
	// ServerID is the MCP source id newly paused.
	ServerID string
	// RevisionID is the tool-exposure revision that recorded the pause.
	RevisionID string
	// OccurredAt is the pause instant.
	OccurredAt time.Time
}

type MCPConnectionRemovedPayload struct {
	events.SafeSealed
	// Author is the identity that recorded the removal.
	Author identity.Quadruple
	// AgentID is the agent whose MCP connection was removed (a registration
	// identity, NOT an isolation principal).
	AgentID string
	// ServerID is the MCP source id that was removed.
	ServerID string
	// RevisionID is the revision that dropped the descriptor + pruned residue.
	RevisionID string
	// OccurredAt is the removal instant.
	OccurredAt time.Time
}

type MCPConnectionResumedPayload struct {
	events.SafeSealed
	// Author is the identity that recorded the resume.
	Author identity.Quadruple
	// AgentID is the agent whose MCP exposure changed.
	AgentID string
	// ServerID is the MCP source id newly resumed.
	ServerID string
	// RevisionID is the tool-exposure revision that recorded the resume.
	RevisionID string
	// OccurredAt is the resume instant.
	OccurredAt time.Time
}

type MCPDiscoveryOriginsSetPayload struct {
	events.SafeSealed
	// Author is the identity that performed the write.
	Author identity.Quadruple
	// AgentID is the agent whose connection allow-list changed (a registration
	// identity, NOT an isolation principal).
	AgentID string
	// ServerID is the MCP source id whose allow-list was replaced.
	ServerID string
	// RevisionID is the revision that recorded the new allow-list.
	RevisionID string
	// Granted is the set of origins newly present versus the prior live set.
	Granted []string
	// Revoked is the set of origins dropped versus the prior live set.
	Revoked []string
	// OccurredAt is the write instant.
	OccurredAt time.Time
}

type MCPTransport string

type NamingDiff struct {
	AutoChanged bool
	AutoFrom    string
	AutoTo      string

	AfterTurnsChanged bool
	AfterTurnsFrom    string
	AfterTurnsTo      string

	RepeatEveryChanged bool
	RepeatEveryFrom    string
	RepeatEveryTo      string

	MaxRepetitionsChanged bool
	MaxRepetitionsFrom    string
	MaxRepetitionsTo      string

	MaxTitleLenChanged bool
	MaxTitleLenFrom    string
	MaxTitleLenTo      string

	ModelChanged bool
	ModelFrom    string
	ModelTo      string
}

type NamingSection struct {
	// Auto enables session auto-naming for the agent. False (the zero value)
	// in a PRESENT section is an explicit off that overrides the yaml fleet
	// default.
	Auto bool `json:"auto,omitempty"`
	// AfterTurns is the completed-run count at which the FIRST auto-name
	// fires (fire on the Nth completed run). Zero resolves to the default
	// (1) at run start; a negative value is rejected at set time.
	AfterTurns int `json:"after_turns,omitempty"`
	// RepeatEvery, when > 0, re-names every N completed turns after the
	// first; 0 (the default) names once only. Negative is rejected at set
	// time.
	RepeatEvery int `json:"repeat_every,omitempty"`
	// MaxRepetitions is the hard cap on the TOTAL number of auto-namings
	// (including the first). It is REQUIRED ≥ 1 whenever RepeatEvery > 0 —
	// no unlimited value exists, so unbounded periodic re-naming is
	// unrepresentable. Ignored when RepeatEvery == 0 (naming happens once).
	MaxRepetitions int `json:"max_repetitions,omitempty"`
	// MaxTitleLen bounds the auto title (runes). Zero resolves to the
	// default (80) at run start; a set value must be in [8, 200].
	MaxTitleLen int `json:"max_title_len,omitempty"`
	// Model, when set, is the model the auto-naming Complete call requests
	// (validated against ModelProfiles at set time); empty uses the run's
	// effective model.
	Model string `json:"model,omitempty"`
}

type OAuthProviderDescriptor struct {
	// Name is the unique provider name (the binding a connection's
	// oauth_provider references). Required.
	Name string `json:"name"`
	// Driver is the OAuth flow driver — validated to be exactly
	// "tokenexchange" (the only writable driver; the non-interactive PULL
	// exchange). Required.
	Driver string `json:"driver"`
	// CredentialSource is the credential-source seam — validated to be exactly
	// "remote" (broker-pull). An empty value is a LOUD reject (in config
	// "" means the `env` source, which this shape forbids). Required.
	CredentialSource string `json:"credential_source"`
	// CredentialBroker names a boot-declared credential broker that
	// pins every credential sink. Required; an unknown name fails loud.
	CredentialBroker string `json:"credential_broker"`
	// Scopes is the requested OAuth scope subset. NON-SECRET. Clamped to the
	// broker's boot scope ceiling at build time — a scope outside the ceiling is
	// dropped, never honoured (an installed descriptor can never widen scope).
	// Optional.
	Scopes []string `json:"scopes,omitempty"`
}

type OAuthProviderSetPayload struct {
	events.SafeSealed
	// Author is the identity that performed the install / uninstall.
	Author identity.Quadruple
	// AgentID is the agent whose installed-provider set changed (a registration
	// identity, NOT an isolation principal).
	AgentID string
	// ProviderName is the installed / uninstalled provider name.
	ProviderName string
	// CredentialBroker is the boot-declared broker the installed provider
	// references by name (empty on uninstall). NON-SECRET.
	CredentialBroker string
	// RevisionID is the recording revision id.
	RevisionID string
	// OccurredAt is the write instant.
	OccurredAt time.Time
}

type OAuthProvidersDiff struct {
	// Added are the provider names present in the to-revision but not the
	// from-revision.
	Added []string
	// Removed are the provider names present in the from-revision but not the
	// to-revision.
	Removed []string
}

type OAuthProvidersSection struct {
	// Providers is the set of installed provider descriptors, keyed by Name.
	// Canonicalised sorted-by-name with a name-unique invariant so a
	// re-ordering does not perturb the content hash.
	Providers []OAuthProviderDescriptor `json:"providers,omitempty"`
}

type PromptLayers struct {
	// Base is the admin-owned, versioned base prompt layer. When set it is
	// the run's base system prompt (overriding the agent's configured
	// default base); unset inherits the configured default.
	Base *string `json:"base,omitempty"`
	// User is the optional higher user-instruction layer that composes
	// ABOVE the base without mutating it (the composition order is the
	// security boundary — the agent-config authorization model).
	User *string `json:"user,omitempty"`
}

type PromptLayersDiff struct {
	// BaseChanged reports whether the base layer text differs.
	BaseChanged bool
	// BaseFrom / BaseTo are the base layer text in the from / to revision.
	BaseFrom string
	BaseTo   string
	// UserChanged reports whether the user layer text differs.
	UserChanged bool
	// UserFrom / UserTo are the user layer text in the from / to revision.
	UserFrom string
	UserTo   string
}

type Registry interface {
	// SetRevision writes a NEW immutable revision pinning payload and
	// advances the active pointer to it. An idempotent re-set of
	// byte-identical canonical content (relative to the current active
	// revision) is a no-op that returns the existing active revision.
	SetRevision(ctx context.Context, id identity.Quadruple, agentID string, scope ConfigScope, payload ConfigPayload) (Revision, error)
	// Active returns the agent's current active revision and whether one
	// exists. No active pointer returns (zero, false, nil).
	Active(ctx context.Context, id identity.Quadruple, agentID string, scope ConfigScope) (Revision, bool, error)
	// Get returns the revision identified by revisionID. A missing
	// revision fails loud with ErrRevisionNotFound.
	Get(ctx context.Context, id identity.Quadruple, agentID, revisionID string, scope ConfigScope) (Revision, error)
	// ListRevisions returns the agent's revision chain newest-first,
	// capped at limit (0 = no cap). Enumeration uses the elevated
	// maintenance scan and filters to the agent's identity slot.
	ListRevisions(ctx context.Context, id identity.Quadruple, agentID string, scope ConfigScope, limit int) ([]Revision, error)
	// Rollback writes a new active pointer to an existing revision
	// WITHOUT mutating or deleting any revision. A missing target fails
	// loud with ErrRevisionNotFound.
	Rollback(ctx context.Context, id identity.Quadruple, agentID, revisionID string, scope ConfigScope) (Revision, error)
	// Diff returns the deterministic compare of two existing revisions.
	Diff(ctx context.Context, id identity.Quadruple, agentID, fromRev, toRev string, scope ConfigScope) (Diff, error)
	// Close releases resources. Idempotent.
	Close(ctx context.Context) error
}

type Revision struct {
	// RevisionID is the unique, time-ordered id of this revision.
	RevisionID string
	// ParentRevisionID is the revision this one descends from (the
	// previously-active revision). Empty for the first revision.
	ParentRevisionID string
	// ContentHash is the full hex-encoded SHA-256 over the revision's
	// canonical (sorted-key) payload encoding.
	ContentHash string
	// Author is the identity that wrote the revision (the audit anchor).
	Author identity.Quadruple
	// CreatedAt is the revision's creation instant (UTC).
	CreatedAt time.Time
	// Payload is the config envelope this revision pins.
	Payload ConfigPayload
}

type RunCompletionHook struct {
	// Tool is the catalog tool name the transcript is dispatched to. An empty
	// tool normalises the RunCompletion to nil BUT preserves the enclosing
	// hooks section (a present section with no tool is the explicit per-agent
	// no-hook that overrides a yaml fleet hook at run start).
	Tool string `json:"tool"`
	// TimeoutMS is the dispatch timeout in milliseconds. Zero falls through
	// to the runtime default at run start. Negative is rejected at set time.
	TimeoutMS int `json:"timeout_ms,omitempty"`
}

type SkillsDiff struct {
	// Added are the skill names present in the to-revision but not the
	// from-revision.
	Added []string
	// Removed are the skill names present in the from-revision but not
	// the to-revision.
	Removed []string
}

type SkillsSelection struct {
	// Names is the set of skill names active for the agent in this
	// revision. Order is not significant — the content hash is computed
	// over a canonical sorted, de-duplicated form so a re-ordering does
	// not perturb the hash.
	Names []string `json:"names"`
}

type ToolExposure struct {
	// PausedServers names MCP servers excluded from the next run's
	// projection (resume is a flag flip, not a re-dial).
	PausedServers []string `json:"paused_servers,omitempty"`
	// DisabledTools names tools the per-tool policy excludes.
	DisabledTools []string `json:"disabled_tools,omitempty"`
	// ServerLoadingModes overrides the default LoadingMode ("always" |
	// "deferred") for a server's TOOL-form descriptors, keyed by the
	// catalog's ToolSourceID. See the precedence order above.
	ServerLoadingModes map[string]string `json:"server_loading_modes,omitempty"`
	// ToolLoadingModes overrides the effective LoadingMode for one exact
	// catalog name ("always" | "deferred"), unconditionally. See the
	// precedence order above.
	ToolLoadingModes map[string]string `json:"tool_loading_modes,omitempty"`
}

type ToolExposureDiff struct {
	// PausedAdded / PausedResumed are the MCP servers newly paused / newly
	// resumed (present-in-to-but-not-from / present-in-from-but-not-to).
	PausedAdded   []string
	PausedResumed []string
	// DisabledAdded / DisabledEnabled are the tools newly disabled / newly
	// re-enabled.
	DisabledAdded   []string
	DisabledEnabled []string
	// ServerLoadingChanges / ToolLoadingChanges are the structured deltas of
	// the per-server / per-tool loading-mode override maps. Sorted by Key.
	ServerLoadingChanges []LoadingModeChange
	ToolLoadingChanges   []LoadingModeChange
}