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"`
	// ExtraSystemBlocks, when non-nil, pins the agent's ORDERED list of
	// named additive prompt blocks. Absent (nil) contributes nothing and
	// leaves the system prompt byte-identical.
	ExtraSystemBlocks *ExtraSystemBlocks `json:"extra_system_blocks,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
	// ExtraSystemBlocks is the structured delta of the ordered additive
	// prompt blocks (added / removed / body-changed by name, plus the
	// order-only reorder flag).
	ExtraSystemBlocks ExtraSystemBlocksDiff
}

type ExtraSystemBlocks struct {
	// Blocks is the ordered list. A slice, never a map: map iteration order
	// is not a composition order.
	Blocks []NamedBlock `json:"blocks"`
}

type ExtraSystemBlocksDiff struct {
	// Added are the block names present only in the to-revision.
	Added []string
	// Removed are the block names present only in the from-revision.
	Removed []string
	// Changed are the names present in both whose BODY differs.
	Changed []string
	// Reordered reports that the two revisions carry the SAME name set in a
	// DIFFERENT order. Order is render order, so a pure re-ordering is a
	// real prompt change and must be visible in the diff.
	Reordered bool
}

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 LLMProviderDescriptor struct {
	// Name is the unique provider-binding name. Required.
	Name string `json:"name"`
	// Provider is the LLM provider the pulled key authenticates (e.g.
	// "openai"). Required.
	Provider string `json:"provider"`
	// CredentialSource is validated to be exactly "remote" (broker-pull).
	// Required.
	CredentialSource string `json:"credential_source"`
	// InferenceBroker names a boot-declared inference broker that pins every
	// credential sink. Required; an unknown name fails loud. NON-SECRET.
	InferenceBroker string `json:"inference_broker"`
	// ModelAllow is the optional model-name allowlist. NON-SECRET.
	ModelAllow []string `json:"model_allow,omitempty"`
}

type LLMProviderSetPayload struct {
	events.SafeSealed
	// Author is the identity that performed the install / rotate.
	Author identity.Quadruple
	// AgentID is the agent whose installed inference-provider binding changed
	// (a registration identity, NOT an isolation principal).
	AgentID string
	// ProviderName is the installed binding name.
	ProviderName string
	// Provider is the LLM provider the pulled key authenticates.
	Provider string
	// InferenceBroker is the boot-declared broker the binding references by
	// name. NON-SECRET.
	InferenceBroker string
	// OccurredAt is the write instant.
	OccurredAt time.Time
}

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 into the MCP `_meta` on every identity-stamped
	// per-call RPC (the deployment's attribution vocabulary). Each key is a
	// `_meta` PATH — a dotted key NESTS, exactly like `injection.meta_key`.
	// Keys are stored as declared; the nesting is a merge-time semantic.
	// Reserved / spec-prefixed keys (at the whole key OR any dot-segment),
	// over-deep paths, and paths colliding with another declared path on the
	// connection are rejected at validation.
	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"`
	// Injection, when set, binds this runtime-added connection to per-user
	// credential INJECTION for a RECEIVER-STYLE MCP server (the acting principal's
	// credential is pulled per outbound call from the named broker and delivered
	// in the declared form). NON-SECRET — it NAMES a boot-declared broker and
	// declares a target key/form; only the broker-pulled value is secret, and it
	// never rides this descriptor. Carried over the wire only behind the
	// fail-closed `tools.allow_wire_injection` opt-in; recorded here so the
	// binding is part of the agent's versioned desired state (diff / rollback).
	// Set only for the http transport; mutually exclusive with OAuthProvider.
	Injection *MCPCredentialInjectionDescriptor `json:"injection,omitempty"`
	// ArtifactByteEligible declares that this connection MAY receive
	// artifact BYTES through egress substitution: the runtime resolving an
	// artifact id the model authored and placing the resolved bytes into
	// the outbound tool-call body. NON-SECRET (a boolean declaration).
	//
	// It is the containment boundary for the feature. The reachable
	// artifact SET is unchanged by it — that stays the dispatching run's
	// own (tenant, user, session) — but the RECIPIENT widens: a remote
	// server may now be handed those bytes.
	//
	// Unlike its wire-writable siblings (the inline OAuth binding, the
	// injection mapping) it sits behind NO fail-closed boot opt-in, and
	// the asymmetry is deliberate: those gates exist because their fields
	// determine where a CREDENTIAL is sent, a boot-declared-only plane,
	// while this one determines where a user's OWN CONTENT is sent —
	// inside the co-tenant-admin trust boundary a shared runtime has
	// already accepted, with one-runtime-per-tenant as the stated remedy
	// for a deployment needing hard isolation. A boot gate would also
	// break the use case: a server attached over the control plane must be
	// usable without a redeploy.
	//
	// Every substitution is recorded (`mcp.artifact_egressed`,
	// fail-closed, before the wire request) — ids, sizes and a digest,
	// never the bytes. Set only for the http transport.
	ArtifactByteEligible bool `json:"artifact_byte_eligible,omitempty"`
	// ArtifactParams maps this server's TOOL names to the parameters on
	// those tools which carry artifact bytes. NON-SECRET (names only).
	// Requires ArtifactByteEligible. Each mapped parameter is validated
	// against the server's OWN discovered inputSchema at attach — it must
	// be declared there, and declared string-typed — so Harbor never
	// asserts an argument shape the server did not publish. Set only for
	// the http transport.
	ArtifactParams map[string][]string `json:"artifact_params,omitempty"`
}

type MCPConnectionLifecyclePayload struct {
	events.SafeSealed
	// Author is the identity that drove the add. On a run-start re-attach there
	// is no admin request: Author carries the RECONCILING RUN's quadruple, whose
	// non-empty RunID is the machine-readable discriminator between the two
	// families (an admin add's RunID is empty).
	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"). On the run-start re-attach events it is
	// "online" for a successful re-establishment and the stable failure CLASS
	// (one of the MCPReattachClass* constants) for a refused / unreachable one —
	// so a reader distinguishes "the third party is down" from "current boot
	// policy refuses this descriptor" without parsing Reason.
	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. On a re-attach
	// failure it may additionally carry a suppressed-attempt count, so a
	// backed-off retry window is bounded and reported rather than silent.
	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 MCPCredentialInjectionDescriptor struct {
	// Provider names the declared OAuth-provider broker the per-user credential is
	// pulled from. Required. NON-SECRET (a name).
	Provider string `json:"provider"`
	// Form selects the injection form: "header" / "basic" / "meta". Required.
	Form string `json:"form"`
	// Header is the target request header name for Form=="header". Required for
	// that form; a redaction-covered credential key, never `Authorization`.
	Header string `json:"header,omitempty"`
	// BasicUsername is the username half for Form=="basic" (the pulled credential
	// is the password half). Optional. NON-SECRET.
	BasicUsername string `json:"basic_username,omitempty"`
	// MetaKey is the target `_meta` key path for Form=="meta", dot-separated for
	// nesting. Required for that form; no reserved segment; redaction-covered leaf.
	MetaKey string `json:"meta_key,omitempty"`
}

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 NamedBlock struct {
	// Name addresses the block within the section. It is unique within the
	// section and drawn from a restricted identifier charset so it stays
	// legible in a transcript and in a diff. It is NEVER emitted as an XML
	// tag — attribution here is a data-model property, not a prompt-syntax
	// one, so the prompt's structural taxonomy never becomes a function of
	// caller input.
	Name string `json:"name"`
	// Body is the block's prompt text. It renders VERBATIM (unescaped) in
	// the operator-trusted additive position — see ExtraSystemBlocks for
	// the trust argument and the obligation it creates.
	Body string `json:"body"`
}

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 the runtime's OWN credential custody. Required in BOTH the name-only
	// and the dev-gated wire shape — the wire descriptor still names a boot broker
	// so no credential-source URL or secret ever rides the wire. NON-SECRET.
	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"`
	// TokenURL is the dev-gated wire-carried RFC-8693 token-exchange endpoint of
	// the NEW server. Persisted (NON-SECRET, a URL); accepted only behind the
	// `allow_wire_oauth_descriptor` boot opt-in and dialed through the
	// token-exchange SSRF backstop. Empty for the name-only shape.
	TokenURL string `json:"token_url,omitempty"`
	// Audience is the dev-gated wire-carried exchanged-token audience of the NEW
	// server. Persisted (NON-SECRET). Empty for the name-only shape.
	Audience string `json:"audience,omitempty"`
	// AllowedDownstreamHosts is the DERIVED downstream sink allow-list for a
	// wire-installed provider — set by the runtime from the bound connection's
	// own URL, NEVER from a wire field. Persisted (NON-SECRET) so a rollback /
	// reconcile rebuilds the provider with the same derived sink. Empty for the
	// name-only shape (its sink is the boot broker's).
	AllowedDownstreamHosts []string `json:"allowed_downstream_hosts,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.
	//
	// opts carries the optional precondition. Its zero value is the
	// unconditional write. When opts.ExpectedContentHash is set, the
	// precondition is evaluated BEFORE the idempotent-re-set
	// short-circuit, so a stale expectation is never converted into a
	// misleading success by a payload that happens to equal the current
	// content; a failed precondition returns ErrRevisionConflict and
	// persists nothing.
	SetRevision(ctx context.Context, id identity.Quadruple, agentID string, scope ConfigScope, payload ConfigPayload, opts SetOptions) (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.
	//
	// opts carries the same optional precondition SetRevision takes: when
	// opts.ExpectedContentHash is set, the CURRENTLY-ACTIVE revision must
	// carry that content hash or the repoint is refused with
	// ErrRevisionConflict and the pointer is left where it was.
	Rollback(ctx context.Context, id identity.Quadruple, agentID, revisionID string, scope ConfigScope, opts SetOptions) (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 SetOptions struct {
	// ExpectedContentHash, when non-empty, requires the agent's ACTIVE
	// revision to carry exactly this content hash at write time. A
	// mismatch — or no active revision at all — fails with
	// ErrRevisionConflict and persists nothing.
	//
	// The reserved value [ExpectNoActiveRevision] ("-") inverts the
	// no-active-revision arm: it REQUIRES the agent to have no active
	// revision, and is refused once one exists. It is what makes the
	// read-modify-write composition protocol expressible at its base case,
	// where a read answers `set:false` and there is no hash to echo. A real
	// content hash is 64 lowercase hex characters, so the sentinel can never
	// collide with one.
	//
	// The expectation is compared against the content hash, not the
	// revision id, because a rollback repoints the active pointer WITHOUT
	// changing the content: a revision-id token would raise a false
	// conflict on the restore path. The guarded quantity is a value, so
	// the token is a value.
	//
	// # The bound on the guarantee — read this before relying on it
	//
	// The comparison is atomic against every other spine writer IN THIS
	// PROCESS, via the agent-config service's per-owner striped write
	// lock, which is held across each door's whole read-modify-write.
	//
	// It is NOT atomic across Runtime processes sharing one StateStore.
	// The StateStore has no compare-and-swap primitive — its own
	// interface godoc says it does not enforce CAS — and the active
	// pointer is written with a fresh event id on every save, so the slot
	// is overwritten unconditionally. Two Runtime processes sharing one
	// Postgres or SQLite store CAN STILL LOSE AN UPDATE, and this option
	// does not claim otherwise. Closing that gap needs a conditional-write
	// primitive on the StateStore interface across the persistence triad;
	// it is a separate change and is not pretended here.
	//
	// What the bounded guarantee is still worth: the window it closes is
	// the READ-TO-WRITE window — seconds to minutes for a human editing a
	// config in the Console, and however long an agent takes to compose
	// one. The window it cannot close cross-process is the driver's own
	// read-modify-write, on the order of microseconds. Single-process the
	// guard is exact; multi-process it is a large reduction in loss
	// probability and not an elimination.
	//
	// # It constrains only the writer that supplies it
	//
	// An unconditional writer can still clobber a conditional one, by
	// design: the token is a precondition on this write, never a lock on
	// the agent. A caller wanting exclusivity needs every writer of that
	// agent's config to participate, which is a deployment convention and
	// not something the runtime enforces — making the token mandatory
	// would break every caller that does not send one.
	ExpectedContentHash string
}

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
}