types

type Agent struct {
	// ID is the agent_id — the stable registration identity.
	ID string `json:"id"`
	// Name is the operator-facing display name.
	Name string `json:"name"`
	// Description is the operator-facing description.
	Description string `json:"description"`
	// Incarnation bumps on every process start.
	Incarnation int64 `json:"incarnation"`
	// VersionHash is the SHA-256 over canonical JSON of AgentConfig.
	// Empty for a HostingRemote agent.
	VersionHash string `json:"version_hash"`
	// Owner is the registration key of the agent — the operator-stable
	// logical-agent key the admin registered it under.
	Owner string `json:"owner"`
	// Status is the lifecycle status pill.
	Status AgentStatus `json:"status"`
	// Health is the operational-health badge.
	Health AgentHealth `json:"health"`
	// Hosting discriminates locally-hosted vs connect-to-remote.
	Hosting AgentHosting `json:"hosting"`
	// PlannerType is the configured planner ("react" / "deterministic"
	// / future). Empty when not declared in AgentConfig.
	PlannerType string `json:"planner_type"`
	// Model is the configured model id. Empty when not declared.
	Model string `json:"model"`
	// ToolsCount is the number of tool bindings on the agent.
	ToolsCount int `json:"tools_count"`
	// MCPCount is the number of MCP-transport tool bindings.
	MCPCount int `json:"mcp_count"`
	// RegisteredAt is the RFC3339 timestamp of the first registration.
	RegisteredAt string `json:"registered_at"`
	// UpdatedAt is the RFC3339 timestamp of the most recent mutation.
	UpdatedAt string `json:"updated_at"`
	// Identity is the (tenant, user, session) triple the agent is
	// registered within — the per-row identity attribution a coordinator
	// uses to attribute a widened (fleet) `agents.list` row to its owning
	// source. For a non-widened listing it is the caller's own scope; for
	// an admin-widened listing it is the agent's own registration scope.
	// `agent_id` (the ID field) is a registration identity, NOT an
	// isolation principal — this Identity triple is the isolation
	// attribution.
	Identity IdentityScope `json:"identity"`
	// IsDefault marks the runtime's synthetic default agent — the one
	// serving the identity scope it was booted with, never written to
	// the Agent Registry's StateStore. false (the zero value, omitted on
	// the wire) for every real registered agent. A consumer uses this to
	// distinguish "the runtime's own agent" from a registered fleet
	// member; it never widens or narrows the isolation tuple. It lets a
	// fleet catalog tell "one agent, not enumerable this way" apart from
	// an empty page (the absence-must-be-representable class).
	IsDefault bool `json:"is_default,omitempty"`
}

type AgentAggregates struct {
	// Total is the count of agents in the filtered view.
	Total int64 `json:"total"`
	// Active is the count of AgentStatusActive agents in the view.
	Active int64 `json:"active"`
	// Paused is the count of AgentStatusPaused agents in the view.
	Paused int64 `json:"paused"`
	// Drained is the count of AgentStatusDrained agents in the view.
	Drained int64 `json:"drained"`
}

type AgentConfig struct {
	// PlannerType is the configured planner ("react" / "deterministic").
	PlannerType string `json:"planner_type"`
	// PlannerConfig is the planner's key/value configuration set
	// (MaxSteps, repair policy, etc.).
	PlannerConfig map[string]string `json:"planner_config,omitempty"`
	// Model is the configured model id.
	Model string `json:"model"`
	// ModelPolicy is the model-selection / model-policy key/value set.
	ModelPolicy map[string]string `json:"model_policy,omitempty"`
	// MaxSteps is the planner's max-steps ceiling (0 ⇒ not declared).
	MaxSteps int `json:"max_steps"`
}

type AgentConfigAddMCPConnectionRequest struct {
	Identity IdentityScope `json:"identity"`
	AgentID  string        `json:"agent_id"`
	// Connection is the NON-SECRET descriptor (name, transport, command/URL).
	Connection AgentConfigMCPConnectionDescriptor `json:"connection"`
	// Headers are OPTIONAL operator-supplied auth headers used ONLY for the
	// live attach (e.g. a bearer token for an http server). They are treated
	// as SECRETS: they flow to the transport but are NEVER persisted in the
	// recorded revision, the diff, or any emitted event (CLAUDE.md §7).
	Headers map[string]string `json:"headers,omitempty"`
}

type AgentConfigAddMCPConnectionResponse struct {
	// Revision is the recorded config revision (set when State is "online"
	// or "auth_required"; nil for a "failed" add, which records no revision).
	Revision *AgentConfigRevisionView `json:"revision,omitempty"`
	// Connection is the NON-SECRET descriptor that was added.
	Connection AgentConfigMCPConnectionDescriptor `json:"connection"`
	// State is the explicit attach lifecycle state: "online" (attached),
	// "failed" (dial / handshake / discover failed — no half-attach), or
	// "auth_required" (parked on the unified pause/resume primitive).
	State string `json:"state"`
	// Reason is a SAFE, operator-facing failure reason (set only when State
	// is "failed"); never a secret.
	Reason string `json:"reason,omitempty"`
	// PauseToken is the unified-pause/resume token the auth_required attach
	// parked on (set only when State is "auth_required"). An opaque runtime
	// handle, NOT a credential.
	PauseToken      string `json:"pause_token,omitempty"`
	ProtocolVersion string `json:"protocol_version"`
}

type AgentConfigConnections struct {
	// Servers is the set of runtime-added MCP connection descriptors.
	Servers []AgentConfigMCPConnectionDescriptor `json:"servers,omitempty"`
}

type AgentConfigConnectionsDiff struct {
	// Added are the connection names present in the to-revision but not the
	// from-revision.
	Added []string `json:"added,omitempty"`
	// Removed are the connection names present in the from-revision but not
	// the to-revision.
	Removed []string `json:"removed,omitempty"`
}

type AgentConfigDiff struct {
	FromRevisionID string                        `json:"from_revision_id"`
	ToRevisionID   string                        `json:"to_revision_id"`
	Skills         AgentConfigSkillsDiff         `json:"skills"`
	ToolExposure   AgentConfigToolExposureDiff   `json:"tool_exposure"`
	PromptLayers   AgentConfigPromptLayersDiff   `json:"prompt_layers"`
	Connections    AgentConfigConnectionsDiff    `json:"connections"`
	OAuthProviders AgentConfigOAuthProvidersDiff `json:"oauth_providers"`
	LLMParams      AgentConfigLLMParamsDiff      `json:"llm_params"`
	Hooks          AgentConfigHooksDiff          `json:"hooks"`
	Naming         AgentConfigNamingDiff         `json:"naming"`
}

type AgentConfigDiffRequest struct {
	Identity     IdentityScope `json:"identity"`
	AgentID      string        `json:"agent_id"`
	FromRevision string        `json:"from_revision"`
	ToRevision   string        `json:"to_revision"`
}

type AgentConfigDiffResponse struct {
	Diff            AgentConfigDiff `json:"diff"`
	ProtocolVersion string          `json:"protocol_version"`
}

type AgentConfigGetRequest struct {
	Identity IdentityScope `json:"identity"`
	AgentID  string        `json:"agent_id"`
}

type AgentConfigGetResponse struct {
	// Revision is the active revision; nil when the agent has no active
	// config (Set is false).
	Revision *AgentConfigRevisionView `json:"revision,omitempty"`
	// Set reports whether an active revision exists.
	Set             bool   `json:"set"`
	ProtocolVersion string `json:"protocol_version"`
}

type AgentConfigHooks struct {
	// RunCompletion, when non-nil, pins the agent's run-completion hook.
	RunCompletion *AgentConfigRunCompletionHook `json:"run_completion,omitempty"`
}

type AgentConfigHooksDiff struct {
	SectionPresentChanged bool   `json:"section_present_changed"`
	SectionPresentFrom    string `json:"section_present_from,omitempty"`
	SectionPresentTo      string `json:"section_present_to,omitempty"`

	RunCompletionToolChanged bool   `json:"run_completion_tool_changed"`
	RunCompletionToolFrom    string `json:"run_completion_tool_from,omitempty"`
	RunCompletionToolTo      string `json:"run_completion_tool_to,omitempty"`

	RunCompletionTimeoutChanged bool   `json:"run_completion_timeout_changed"`
	RunCompletionTimeoutFrom    string `json:"run_completion_timeout_from,omitempty"`
	RunCompletionTimeoutTo      string `json:"run_completion_timeout_to,omitempty"`
}

type AgentConfigLLMParams struct {
	// Model, when set, is the model the agent's next run requests
	// (overriding the tenant-wide baseline / config default).
	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").
	ReasoningEffort *string `json:"reasoning_effort,omitempty"`
}

type AgentConfigLLMParamsDiff struct {
	ModelChanged bool   `json:"model_changed"`
	ModelFrom    string `json:"model_from,omitempty"`
	ModelTo      string `json:"model_to,omitempty"`

	TemperatureChanged bool   `json:"temperature_changed"`
	TemperatureFrom    string `json:"temperature_from,omitempty"`
	TemperatureTo      string `json:"temperature_to,omitempty"`

	MaxTokensChanged bool   `json:"max_tokens_changed"`
	MaxTokensFrom    string `json:"max_tokens_from,omitempty"`
	MaxTokensTo      string `json:"max_tokens_to,omitempty"`

	ReasoningEffortChanged bool   `json:"reasoning_effort_changed"`
	ReasoningEffortFrom    string `json:"reasoning_effort_from,omitempty"`
	ReasoningEffortTo      string `json:"reasoning_effort_to,omitempty"`
}

type AgentConfigLLMProviderDescriptor 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", "anthropic"). Required.
	Provider string `json:"provider"`
	// CredentialSource is the inference-plane credential-source seam —
	// validated to be exactly "remote" (broker-pull). An empty value is a
	// LOUD reject ("" means the env source, which is config/file-only).
	// 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 the binding restricts
	// the provider to. NON-SECRET. Optional.
	ModelAllow []string `json:"model_allow,omitempty"`
}

type AgentConfigListRevisionsRequest struct {
	Identity IdentityScope `json:"identity"`
	AgentID  string        `json:"agent_id"`
	// Limit caps the returned chain length. 0 = no cap.
	Limit int `json:"limit,omitempty"`
}

type AgentConfigListRevisionsResponse struct {
	Revisions       []AgentConfigRevisionView `json:"revisions"`
	ProtocolVersion string                    `json:"protocol_version"`
}

type AgentConfigLoadingModeChange struct {
	Key  string `json:"key"`
	From string `json:"from,omitempty"`
	To   string `json:"to,omitempty"`
}

type AgentConfigMCPConnectionDescriptor struct {
	// Name is the unique MCP source id. Required.
	Name string `json:"name"`
	// Transport is the wire transport — "stdio" or "http".
	Transport string `json:"transport"`
	// Command is the stdio argv (argv[0] is the binary; no shell). Set for
	// the stdio transport.
	Command []string `json:"command,omitempty"`
	// URL is the http(s) endpoint. Set for the http transport.
	URL string `json:"url,omitempty"`
	// OAuthProvider names a declared OAuth provider to bind for per-identity
	// southbound bearer injection. NON-SECRET (a provider name). Set only for
	// the http transport; empty leaves the connection on its static headers.
	OAuthProvider string `json:"oauth_provider,omitempty"`
	// MetaAnnotations is a static, NON-SECRET set of operator key/values
	// merged verbatim into the MCP `_meta` on every identity-stamped call.
	// Reserved / spec-prefixed keys are rejected at attach.
	MetaAnnotations map[string]string `json:"meta_annotations,omitempty"`
	// OAuth is an OPTIONAL inline OAuth-provider binding carried over the wire
	// for this connection (a coordinator standing up a new OAuth-fronted MCP
	// server without a pre-installed provider). It is mutually exclusive with
	// OAuthProvider (bind a name that already exists vs. carry the full binding
	// inline). It is accepted ONLY behind the fail-closed
	// `tools.allow_wire_oauth_descriptor` boot opt-in (default off): with the
	// opt-in off an inline descriptor carrying any credential-sink field is
	// rejected, exactly as the name-only binding rejects a sink field today. When
	// opted in, the exchanged token's downstream sink (`allowed_downstream_hosts`)
	// is DERIVED from this connection's own URL — never a wire-supplied list — and
	// the wire `token_url` faces the identical token-exchange SSRF backstop the
	// boot path uses. Set only for the http transport.
	OAuth *AgentConfigOAuthProviderDescriptor `json:"oauth,omitempty"`
	// OAuthDiscoveryAllowedOrigins is the explicit per-connection cross-origin
	// allow-list of public https origins the OAuth-requirement discovery walker
	// may fetch authorization-server metadata from. NON-SECRET (an origin
	// allow-list) — revisioned + diffable + rollback-able, and 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 if it resolves
	// private / loopback). Set only for the http transport.
	OAuthDiscoveryAllowedOrigins []string `json:"oauth_discovery_allowed_origins,omitempty"`
}

type AgentConfigNaming struct {
	// Auto enables session auto-naming for the agent (false in a present
	// section = 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; 0 inherits the runtime default (1).
	AfterTurns int `json:"after_turns,omitempty"`
	// RepeatEvery, when > 0, re-names every N completed turns after the
	// first; 0 names once only.
	RepeatEvery int `json:"repeat_every,omitempty"`
	// MaxRepetitions caps the TOTAL auto-namings (including the first);
	// required ≥ 1 when RepeatEvery > 0. Ignored when RepeatEvery == 0.
	MaxRepetitions int `json:"max_repetitions,omitempty"`
	// MaxTitleLen bounds the auto title in runes; 0 inherits the runtime
	// default (80). A set value must be in [8, 200].
	MaxTitleLen int `json:"max_title_len,omitempty"`
	// Model, when set, is the model the auto-naming call requests (empty =
	// the run's effective model).
	Model string `json:"model,omitempty"`
}

type AgentConfigNamingDiff struct {
	AutoChanged bool   `json:"auto_changed"`
	AutoFrom    string `json:"auto_from,omitempty"`
	AutoTo      string `json:"auto_to,omitempty"`

	AfterTurnsChanged bool   `json:"after_turns_changed"`
	AfterTurnsFrom    string `json:"after_turns_from,omitempty"`
	AfterTurnsTo      string `json:"after_turns_to,omitempty"`

	RepeatEveryChanged bool   `json:"repeat_every_changed"`
	RepeatEveryFrom    string `json:"repeat_every_from,omitempty"`
	RepeatEveryTo      string `json:"repeat_every_to,omitempty"`

	MaxRepetitionsChanged bool   `json:"max_repetitions_changed"`
	MaxRepetitionsFrom    string `json:"max_repetitions_from,omitempty"`
	MaxRepetitionsTo      string `json:"max_repetitions_to,omitempty"`

	MaxTitleLenChanged bool   `json:"max_title_len_changed"`
	MaxTitleLenFrom    string `json:"max_title_len_from,omitempty"`
	MaxTitleLenTo      string `json:"max_title_len_to,omitempty"`

	ModelChanged bool   `json:"model_changed"`
	ModelFrom    string `json:"model_from,omitempty"`
	ModelTo      string `json:"model_to,omitempty"`
}

type AgentConfigOAuthProviderDescriptor struct {
	// Name is the unique provider name (a connection's oauth_provider binding
	// references it). 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. Required.
	CredentialSource string `json:"credential_source"`
	// CredentialBroker names a boot-declared credential broker that pins the
	// runtime's OWN credential custody (the coordinator pull endpoint, the
	// service-token env name, the org client credential). 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 (a name).
	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. Optional.
	Scopes []string `json:"scopes,omitempty"`
	// TokenURL is the NEW server's RFC-8693 token-exchange endpoint. A wire-carried
	// field: accepted ONLY behind the `tools.allow_wire_oauth_descriptor` opt-in,
	// and dialed through the token-exchange SSRF backstop (private / link-local /
	// ULA / unspecified refused post-DNS, every redirect refused, no proxy).
	// Rejected when the opt-in is off. Optional.
	TokenURL string `json:"token_url,omitempty"`
	// Audience is the NEW server's exchanged-token audience. A wire-carried field:
	// accepted ONLY behind the opt-in; rejected when off. Optional.
	Audience string `json:"audience,omitempty"`
}

type AgentConfigOAuthProviders struct {
	// Providers is the set of installed provider descriptors.
	Providers []AgentConfigOAuthProviderDescriptor `json:"providers,omitempty"`
}

type AgentConfigOAuthProvidersDiff struct {
	// Added are the provider names present in the to-revision but not the
	// from-revision.
	Added []string `json:"added,omitempty"`
	// Removed are the provider names present in the from-revision but not the
	// to-revision.
	Removed []string `json:"removed,omitempty"`
}

type AgentConfigPayload struct {
	// PromptLayers, when non-nil, pins the agent's layered system prompt
	// (operator base + optional user layer) for the revision.
	PromptLayers *AgentConfigPromptLayers `json:"prompt_layers,omitempty"`
	// Skills, when non-nil, pins the agent's skills membership for the
	// revision.
	Skills *AgentConfigSkillsSelection `json:"skills,omitempty"`
	// ToolExposure, when non-nil, pins the agent's MCP-exposure / per-tool
	// policy for the revision.
	ToolExposure *AgentConfigToolExposure `json:"tool_exposure,omitempty"`
	// Connections, when non-nil, pins the agent's runtime-added MCP
	// connection descriptors (non-secret) for the revision.
	Connections *AgentConfigConnections `json:"connections,omitempty"`
	// OAuthProviders, when non-nil, pins the agent's Protocol-installed
	// (zero-URL) OAuth provider descriptors for the revision.
	OAuthProviders *AgentConfigOAuthProviders `json:"oauth_providers,omitempty"`
	// LLMParams, when non-nil, pins the agent's per-agent LLM-parameter
	// section (model / temperature / max-tokens / reasoning-effort) for the
	// revision.
	LLMParams *AgentConfigLLMParams `json:"llm_params,omitempty"`
	// Hooks, when non-nil, pins the agent's run-lifecycle-hook section (the
	// run-completion hook) for the revision.
	Hooks *AgentConfigHooks `json:"hooks,omitempty"`
	// Naming, when non-nil, pins the agent's session auto-naming policy
	// section for the revision.
	Naming *AgentConfigNaming `json:"naming,omitempty"`
}

type AgentConfigPromptLayers struct {
	// Base is the operator-owned 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 composed above the
	// base in the lower-trust guidance position.
	User *string `json:"user,omitempty"`
}

type AgentConfigPromptLayersDiff struct {
	// BaseChanged reports whether the base layer text differs.
	BaseChanged bool `json:"base_changed"`
	// BaseFrom / BaseTo are the base layer text in the from / to revision.
	BaseFrom string `json:"base_from,omitempty"`
	BaseTo   string `json:"base_to,omitempty"`
	// UserChanged reports whether the user layer text differs.
	UserChanged bool `json:"user_changed"`
	// UserFrom / UserTo are the user layer text in the from / to revision.
	UserFrom string `json:"user_from,omitempty"`
	UserTo   string `json:"user_to,omitempty"`
}

type AgentConfigRemoveMCPConnectionRequest struct {
	Identity IdentityScope `json:"identity"`
	AgentID  string        `json:"agent_id"`
	// Name is the runtime-added MCP source id to remove.
	Name string `json:"name"`
}

type AgentConfigRemoveMCPConnectionResponse struct {
	// Revision is the recorded config revision whose connections section
	// dropped the named descriptor (with the server's tool-exposure residue
	// pruned in the same atomic revision).
	Revision AgentConfigRevisionView `json:"revision"`
	// Name is the removed MCP source id (echoed for the caller's convenience).
	Name            string `json:"name"`
	ProtocolVersion string `json:"protocol_version"`
}

type AgentConfigRemoveOAuthProviderRequest struct {
	Identity IdentityScope `json:"identity"`
	AgentID  string        `json:"agent_id"`
	// Name is the installed provider name to uninstall.
	Name string `json:"name"`
}

type AgentConfigRemoveOAuthProviderResponse struct {
	// Revision is the recorded config revision whose oauth-providers section
	// dropped the named descriptor.
	Revision AgentConfigRevisionView `json:"revision"`
	// Name is the removed provider name (echoed).
	Name string `json:"name"`
	// Uninstalled reports whether the provider was uninstalled live (true on
	// every served success; false only degrades to the revisioned write when no
	// live provider installer is wired on this runtime).
	Uninstalled     bool   `json:"uninstalled"`
	ProtocolVersion string `json:"protocol_version"`
}

type AgentConfigRevisionView struct {
	// RevisionID is the revision's unique, time-ordered id.
	RevisionID string `json:"revision_id"`
	// ParentRevisionID is the revision this one descends from (empty for
	// the first revision).
	ParentRevisionID string `json:"parent_revision_id,omitempty"`
	// ContentHash is the full hex SHA-256 over the revision's canonical
	// payload encoding (for diff/audit correlation; never the content).
	ContentHash string `json:"content_hash"`
	// AuthorTenant / AuthorUser identify the author (the audit anchor).
	// The author's session is intentionally omitted — the audit anchor is
	// the (tenant, user) actor, not the session.
	AuthorTenant string `json:"author_tenant,omitempty"`
	AuthorUser   string `json:"author_user,omitempty"`
	// CreatedAt is the revision's creation instant.
	CreatedAt time.Time `json:"created_at"`
	// Payload is the config envelope this revision pins.
	Payload AgentConfigPayload `json:"payload"`
}

type AgentConfigRollbackRequest struct {
	Identity   IdentityScope `json:"identity"`
	AgentID    string        `json:"agent_id"`
	RevisionID string        `json:"revision_id"`
}

type AgentConfigRollbackResponse struct {
	Revision        AgentConfigRevisionView `json:"revision"`
	ProtocolVersion string                  `json:"protocol_version"`
}

type AgentConfigRunCompletionHook struct {
	// Tool is the catalog tool name the transcript is dispatched to.
	Tool string `json:"tool"`
	// TimeoutMS is the dispatch timeout in milliseconds. Zero inherits the
	// runtime default at run start.
	TimeoutMS int `json:"timeout_ms,omitempty"`
}

type AgentConfigSessionOverlay struct {
	UserPrompt      string   `json:"user_prompt,omitempty"`
	DisabledServers []string `json:"disabled_servers,omitempty"`
	DisabledTools   []string `json:"disabled_tools,omitempty"`
	PersonalSkills  []string `json:"personal_skills,omitempty"`
}

type AgentConfigSessionSetSourceDisablesRequest struct {
	Identity        IdentityScope `json:"identity"`
	AgentID         string        `json:"agent_id"`
	DisabledServers []string      `json:"disabled_servers,omitempty"`
	DisabledTools   []string      `json:"disabled_tools,omitempty"`
}

type AgentConfigSessionSetSourceDisablesResponse struct {
	Overlay         AgentConfigSessionOverlay `json:"overlay"`
	ProtocolVersion string                    `json:"protocol_version"`
}

type AgentConfigSessionSetUserPromptRequest struct {
	Identity   IdentityScope `json:"identity"`
	AgentID    string        `json:"agent_id"`
	UserPrompt string        `json:"user_prompt"`
}

type AgentConfigSessionSetUserPromptResponse struct {
	Overlay         AgentConfigSessionOverlay `json:"overlay"`
	ProtocolVersion string                    `json:"protocol_version"`
}

type AgentConfigSessionSkillsDeleteRequest struct {
	Identity IdentityScope `json:"identity"`
	AgentID  string        `json:"agent_id"`
	Name     string        `json:"name"`
}

type AgentConfigSessionSkillsDeleteResponse struct {
	Overlay         AgentConfigSessionOverlay `json:"overlay"`
	ProtocolVersion string                    `json:"protocol_version"`
}

type AgentConfigSessionSkillsListRequest struct {
	Identity IdentityScope `json:"identity"`
	AgentID  string        `json:"agent_id"`
}

type AgentConfigSessionSkillsListResponse struct {
	Skills          []AgentConfigSkillSummary `json:"skills"`
	ProtocolVersion string                    `json:"protocol_version"`
}

type AgentConfigSessionSkillsUpsertRequest struct {
	Identity IdentityScope         `json:"identity"`
	AgentID  string                `json:"agent_id"`
	Skill    AgentConfigSkillInput `json:"skill"`
}

type AgentConfigSessionSkillsUpsertResponse struct {
	Skill           AgentConfigSkillSummary   `json:"skill"`
	Overlay         AgentConfigSessionOverlay `json:"overlay"`
	ProtocolVersion string                    `json:"protocol_version"`
}

type AgentConfigSetLLMParamsRequest struct {
	Identity  IdentityScope        `json:"identity"`
	AgentID   string               `json:"agent_id"`
	LLMParams AgentConfigLLMParams `json:"llm_params"`
}

type AgentConfigSetLLMParamsResponse struct {
	Revision        AgentConfigRevisionView `json:"revision"`
	ProtocolVersion string                  `json:"protocol_version"`
}

type AgentConfigSetLLMProviderRequest struct {
	Identity IdentityScope `json:"identity"`
	AgentID  string        `json:"agent_id"`
	// Provider is the ZERO-URL descriptor to install.
	Provider AgentConfigLLMProviderDescriptor `json:"provider"`
}

type AgentConfigSetLLMProviderResponse struct {
	// Name is the installed provider-binding name (echoed).
	Name string `json:"name"`
	// Installed reports whether the binding took effect on the live provider
	// set (false only degrades when no live installer is wired on this
	// runtime — the write is then rejected loud, never a silent no-op).
	Installed       bool   `json:"installed"`
	ProtocolVersion string `json:"protocol_version"`
}

type AgentConfigSetMCPDiscoveryOriginsRequest struct {
	Identity IdentityScope `json:"identity"`
	AgentID  string        `json:"agent_id"`
	// Name is the runtime-added MCP source id whose allow-list is replaced.
	Name string `json:"name"`
	// AllowedOrigins is the FULL replacement allow-list (empty clears it).
	AllowedOrigins []string `json:"allowed_origins"`
}

type AgentConfigSetMCPDiscoveryOriginsResponse struct {
	// Revision is the recorded config revision carrying the new allow-list.
	Revision AgentConfigRevisionView `json:"revision"`
	// Name is the connection whose allow-list was replaced (echoed).
	Name string `json:"name"`
	// Granted is the set of origins newly present versus the prior live set.
	Granted []string `json:"granted,omitempty"`
	// Revoked is the set of origins dropped versus the prior live set.
	Revoked []string `json:"revoked,omitempty"`
	// AppliedLive reports whether the allow-list was applied to the live MCP
	// registry (true on every served success; false only degrades to the
	// revisioned write when no live registry applier is wired on this runtime).
	AppliedLive     bool   `json:"applied_live"`
	ProtocolVersion string `json:"protocol_version"`
}

type AgentConfigSetOAuthProviderRequest struct {
	Identity IdentityScope `json:"identity"`
	AgentID  string        `json:"agent_id"`
	// Provider is the ZERO-URL descriptor to install.
	Provider AgentConfigOAuthProviderDescriptor `json:"provider"`
}

type AgentConfigSetOAuthProviderResponse struct {
	// Revision is the recorded config revision carrying the installed provider.
	Revision AgentConfigRevisionView `json:"revision"`
	// Name is the installed provider name (echoed).
	Name            string `json:"name"`
	ProtocolVersion string `json:"protocol_version"`
}

type AgentConfigSetPromptLayersRequest struct {
	Identity     IdentityScope           `json:"identity"`
	AgentID      string                  `json:"agent_id"`
	PromptLayers AgentConfigPromptLayers `json:"prompt_layers"`
}

type AgentConfigSetPromptLayersResponse struct {
	Revision        AgentConfigRevisionView `json:"revision"`
	ProtocolVersion string                  `json:"protocol_version"`
}

type AgentConfigSetRevisionRequest struct {
	Identity IdentityScope      `json:"identity"`
	AgentID  string             `json:"agent_id"`
	Payload  AgentConfigPayload `json:"payload"`
}

type AgentConfigSetRevisionResponse struct {
	Revision        AgentConfigRevisionView `json:"revision"`
	ProtocolVersion string                  `json:"protocol_version"`
}

type AgentConfigSetToolExposureRequest struct {
	Identity     IdentityScope           `json:"identity"`
	AgentID      string                  `json:"agent_id"`
	ToolExposure AgentConfigToolExposure `json:"tool_exposure"`
}

type AgentConfigSetToolExposureResponse struct {
	Revision        AgentConfigRevisionView `json:"revision"`
	ProtocolVersion string                  `json:"protocol_version"`
}

type AgentConfigSkillInput struct {
	Name        string   `json:"name"`
	Title       string   `json:"title,omitempty"`
	Description string   `json:"description,omitempty"`
	Trigger     string   `json:"trigger"`
	TaskType    string   `json:"task_type,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	Steps       []string `json:"steps"`
	// Origin is the skill provenance (pack | generated). A skills.upsert
	// over a pack-origin skill with a non-pack input is refused (the
	// `ErrPackOverwriteRefused` path surfaces as a typed Protocol error).
	Origin string `json:"origin"`
	// Scope is the skill visibility (session | project | tenant | global).
	Scope string `json:"scope"`
}

type AgentConfigSkillSummary struct {
	Name        string    `json:"name"`
	Title       string    `json:"title,omitempty"`
	Trigger     string    `json:"trigger,omitempty"`
	TaskType    string    `json:"task_type,omitempty"`
	Origin      string    `json:"origin"`
	Scope       string    `json:"scope"`
	ContentHash string    `json:"content_hash,omitempty"`
	UpdatedAt   time.Time `json:"updated_at"`
}

type AgentConfigSkillsDeleteRequest struct {
	Identity IdentityScope `json:"identity"`
	AgentID  string        `json:"agent_id"`
	Name     string        `json:"name"`
}

type AgentConfigSkillsDeleteResponse struct {
	Revision        AgentConfigRevisionView `json:"revision"`
	ProtocolVersion string                  `json:"protocol_version"`
}

type AgentConfigSkillsDiff struct {
	// Added are the skill names present in the to-revision but not the
	// from-revision.
	Added []string `json:"added,omitempty"`
	// Removed are the skill names present in the from-revision but not the
	// to-revision.
	Removed []string `json:"removed,omitempty"`
}

type AgentConfigSkillsListRequest struct {
	Identity IdentityScope `json:"identity"`
	AgentID  string        `json:"agent_id"`
}

type AgentConfigSkillsListResponse struct {
	Skills          []AgentConfigSkillSummary `json:"skills"`
	ProtocolVersion string                    `json:"protocol_version"`
}

type AgentConfigSkillsSelection struct {
	// Names is the membership set of skill names active for the agent.
	Names []string `json:"names"`
}

type AgentConfigSkillsUpsertRequest struct {
	Identity IdentityScope         `json:"identity"`
	AgentID  string                `json:"agent_id"`
	Skill    AgentConfigSkillInput `json:"skill"`
}

type AgentConfigSkillsUpsertResponse struct {
	Revision        AgentConfigRevisionView `json:"revision"`
	Skill           AgentConfigSkillSummary `json:"skill"`
	ProtocolVersion string                  `json:"protocol_version"`
}

type AgentConfigToolExposure struct {
	// PausedServers names the MCP source ids excluded from the next run's
	// projection (resume is a flag flip, not a re-dial).
	PausedServers []string `json:"paused_servers,omitempty"`
	// DisabledTools names the individually-disabled tools (`<source>_<tool>`).
	DisabledTools []string `json:"disabled_tools,omitempty"`
	// ServerLoadingModes overrides the loading mode for a server's TOOL-form
	// descriptors, keyed by MCP source id.
	ServerLoadingModes map[string]string `json:"server_loading_modes,omitempty"`
	// ToolLoadingModes overrides the loading mode for one exact catalog
	// name, unconditionally.
	ToolLoadingModes map[string]string `json:"tool_loading_modes,omitempty"`
}

type AgentConfigToolExposureDiff struct {
	// PausedAdded / PausedResumed are the MCP servers newly paused / newly
	// resumed across the two revisions.
	PausedAdded   []string `json:"paused_added,omitempty"`
	PausedResumed []string `json:"paused_resumed,omitempty"`
	// DisabledAdded / DisabledEnabled are the tools newly disabled / newly
	// re-enabled across the two revisions.
	DisabledAdded   []string `json:"disabled_added,omitempty"`
	DisabledEnabled []string `json:"disabled_enabled,omitempty"`
	// ServerLoadingChanges / ToolLoadingChanges are the structured deltas of
	// the per-server / per-tool loading-mode override maps.
	ServerLoadingChanges []AgentConfigLoadingModeChange `json:"server_loading_changes,omitempty"`
	ToolLoadingChanges   []AgentConfigLoadingModeChange `json:"tool_loading_changes,omitempty"`
}

type AgentConfigUserDiffRequest struct {
	Identity     IdentityScope `json:"identity"`
	AgentID      string        `json:"agent_id"`
	FromRevision string        `json:"from_revision"`
	ToRevision   string        `json:"to_revision"`
}

type AgentConfigUserDiffResponse struct {
	Diff            AgentConfigDiff `json:"diff"`
	ProtocolVersion string          `json:"protocol_version"`
}

type AgentConfigUserGetRequest struct {
	Identity IdentityScope `json:"identity"`
	AgentID  string        `json:"agent_id"`
}

type AgentConfigUserGetResponse struct {
	// Revision is the active revision; nil when the caller has no durable
	// variant (Set is false).
	Revision *AgentConfigRevisionView `json:"revision,omitempty"`
	// Set reports whether an active user revision exists.
	Set             bool   `json:"set"`
	ProtocolVersion string `json:"protocol_version"`
}

type AgentConfigUserListRevisionsRequest struct {
	Identity IdentityScope `json:"identity"`
	AgentID  string        `json:"agent_id"`
	// Limit caps the returned chain length. 0 = no cap.
	Limit int `json:"limit,omitempty"`
}

type AgentConfigUserListRevisionsResponse struct {
	Revisions       []AgentConfigRevisionView `json:"revisions"`
	ProtocolVersion string                    `json:"protocol_version"`
}

type AgentConfigUserPayload struct {
	// UserPrompt is the user instruction layer that composes ABOVE the
	// operator base (the prompt projection consumes this).
	UserPrompt string `json:"user_prompt,omitempty"`
	// DisabledServers names the MCP servers the user narrows out (the
	// tool-exposure projection consumes this); narrow-only — there is no
	// enable path.
	DisabledServers []string `json:"disabled_servers,omitempty"`
	// DisabledTools names the individual tools the user narrows out (the
	// tool-exposure projection consumes this).
	DisabledTools []string `json:"disabled_tools,omitempty"`
	// PersonalSkills names the user's personal skill membership for the
	// variant.
	PersonalSkills []string `json:"personal_skills,omitempty"`
}

type AgentConfigUserRollbackRequest struct {
	Identity   IdentityScope `json:"identity"`
	AgentID    string        `json:"agent_id"`
	RevisionID string        `json:"revision_id"`
}

type AgentConfigUserRollbackResponse struct {
	Revision        AgentConfigRevisionView `json:"revision"`
	ProtocolVersion string                  `json:"protocol_version"`
}

type AgentConfigUserSetRevisionRequest struct {
	Identity IdentityScope          `json:"identity"`
	AgentID  string                 `json:"agent_id"`
	Payload  AgentConfigUserPayload `json:"payload"`
}

type AgentConfigUserSetRevisionResponse struct {
	Revision        AgentConfigRevisionView `json:"revision"`
	ProtocolVersion string                  `json:"protocol_version"`
}

type AgentControlRequest struct {
	// Identity is the (tenant, user, session) scope. Mandatory.
	Identity IdentityScope `json:"identity"`
	// ID is the agent_id to control.
	ID string `json:"id"`
	// Reason is the operator-supplied control reason (redacted, audited).
	Reason string `json:"reason,omitempty"`
}

type AgentControlResponse struct {
	// AgentID echoes the controlled agent_id.
	AgentID string `json:"agent_id"`
	// Command is the applied control verb: pause / drain / restart /
	// force_stop / deregister.
	Command string `json:"command"`
	// Status is the agent's post-control lifecycle status.
	Status AgentStatus `json:"status"`
}

type AgentCostCeiling struct {
	// Tier is the identity tier the ceiling applies to.
	Tier string `json:"tier"`
	// LimitUSD is the configured spend ceiling in USD.
	LimitUSD float64 `json:"limit_usd"`
	// SpendUSD is the current accumulated spend in USD.
	SpendUSD float64 `json:"spend_usd"`
}

type AgentFilter struct {
	// Status narrows to agents whose Status is in the set; empty = all.
	Status []AgentStatus `json:"status,omitempty"`
	// PlannerType narrows to agents whose PlannerType is in the set;
	// empty = all.
	PlannerType []string `json:"planner_type,omitempty"`
	// Search is a free-text query over Name + Description (case-fold).
	Search string `json:"search,omitempty"`
	// TenantIDs is the admin-widened FLEET-enumeration selector: when
	// non-empty, `agents.list` enumerates every registered agent across
	// ALL sessions of the named tenants (a coordinator control plane
	// rendering a fleet-wide Agents catalog), not just the caller's own
	// triple. It mirrors `SessionFilter.TenantIDs` and the tasks analogue.
	// Widening requires the verified `auth.ScopeAdmin` claim — a non-empty
	// TenantIDs without the claim fails closed with the scope-mismatch
	// error, never a silent narrowing. Empty (the default) is
	// byte-compatible with the identity-scoped read.
	TenantIDs []string `json:"tenant_ids,omitempty"`
}

type AgentGetRequest struct {
	// Identity is the (tenant, user, session) scope. Mandatory.
	Identity IdentityScope `json:"identity"`
	// ID is the agent_id to fetch.
	ID string `json:"id"`
}

type AgentGetResponse struct {
	// Agent is the catalog-row projection.
	Agent Agent `json:"agent"`
	// Config is the agent's configuration projection.
	Config AgentConfig `json:"config"`
	// AgentCardRef references the canonical A2A AgentCard for a
	// HostingRemote agent. Empty for a HostingLocal agent.
	AgentCardRef string `json:"agent_card_ref,omitempty"`
}

type AgentGovernance struct {
	// Ceilings is the per-identity-tier cost ceilings + spend.
	Ceilings []AgentCostCeiling `json:"ceilings"`
	// RateLimits is the per-identity-tier rate-limit posture.
	RateLimits []AgentRateLimit `json:"rate_limits"`
}

type AgentGovernanceRequest struct {
	// Identity is the (tenant, user, session) scope. Mandatory.
	Identity IdentityScope `json:"identity"`
	// ID is the agent_id whose governance posture to fetch.
	ID string `json:"id"`
}

type AgentGovernanceResponse struct {
	// AgentID echoes the requested agent_id.
	AgentID string `json:"agent_id"`
	// Governance is the agent's governance posture.
	Governance AgentGovernance `json:"governance"`
}

type AgentHealth string

type AgentHosting string

type AgentListRequest struct {
	// Identity is the (tenant, user, session) scope. Mandatory.
	Identity IdentityScope `json:"identity"`
	// Filter is the optional facet filter.
	Filter AgentFilter `json:"filter,omitempty"`
	// Page is the 1-based page index. <= 0 is treated as page 1.
	Page int `json:"page,omitempty"`
	// PageSize is the rows-per-page. 0 ⇒ DefaultAgentListPageSize.
	PageSize int `json:"page_size,omitempty"`
}

type AgentListResponse struct {
	// Agents is the page of catalog rows.
	Agents []Agent `json:"agents"`
	// Page is the 1-based page index this response covers.
	Page int `json:"page"`
	// PageSize is the rows-per-page applied.
	PageSize int `json:"page_size"`
	// PageCount is the total number of pages in the filtered view.
	PageCount int `json:"page_count"`
	// TotalRows is the total row count in the filtered view.
	TotalRows int64 `json:"total_rows"`
	// Aggregates is the four counters over the filtered view.
	Aggregates AgentAggregates `json:"aggregates"`
}

type AgentMemoryBinding struct {
	// StrategyID is the memory strategy id.
	StrategyID string `json:"strategy_id"`
	// TTLSeconds is the configured memory TTL in seconds (0 ⇒ no TTL).
	TTLSeconds int64 `json:"ttl_seconds"`
	// Scope is the memory scope: "session" / "user" / "tenant".
	Scope string `json:"scope"`
}

type AgentMemoryRequest struct {
	// Identity is the (tenant, user, session) scope. Mandatory.
	Identity IdentityScope `json:"identity"`
	// ID is the agent_id whose memory binding to fetch.
	ID string `json:"id"`
}

type AgentMemoryResponse struct {
	// AgentID echoes the requested agent_id.
	AgentID string `json:"agent_id"`
	// Binding is the agent's memory-strategy binding.
	Binding AgentMemoryBinding `json:"binding"`
}

type AgentMetrics struct {
	// ActiveAgents is the count of AgentStatusActive agents in scope.
	ActiveAgents int64 `json:"active_agents"`
	// RunningTasks is the count of in-flight tasks across those agents.
	RunningTasks int64 `json:"running_tasks"`
	// TotalCostUSD is the total accumulated spend across those agents.
	TotalCostUSD float64 `json:"total_cost_usd"`
	// TotalTokens is the total token consumption across those agents.
	TotalTokens int64 `json:"total_tokens"`
}

type AgentMetricsRequest struct {
	// Identity is the (tenant, user, session) scope. Mandatory.
	Identity IdentityScope `json:"identity"`
}

type AgentMetricsResponse struct {
	// Metrics is the registry-wide rollup.
	Metrics AgentMetrics `json:"metrics"`
}

type AgentPermissions struct {
	// Model is the permission model: "implicit" (V1 default) or
	// "explicit" (post-V1).
	Model string `json:"model"`
	// Description is the operator-facing explanation of the model.
	Description string `json:"description"`
	// AllowedPrincipals is the explicit ACL when Model is "explicit";
	// empty for the implicit model.
	AllowedPrincipals []string `json:"allowed_principals,omitempty"`
}

type AgentPermissionsRequest struct {
	// Identity is the (tenant, user, session) scope. Mandatory.
	Identity IdentityScope `json:"identity"`
	// ID is the agent_id whose permission model to fetch.
	ID string `json:"id"`
}

type AgentPermissionsResponse struct {
	// AgentID echoes the requested agent_id.
	AgentID string `json:"agent_id"`
	// Permissions is the agent's permission model.
	Permissions AgentPermissions `json:"permissions"`
}

type AgentRateLimit struct {
	// Tier is the identity tier the rate limit applies to.
	Tier string `json:"tier"`
	// RequestsPerMinute is the configured per-minute request ceiling.
	RequestsPerMinute int64 `json:"requests_per_minute"`
	// MaxTokens is the configured per-request MaxTokens ceiling.
	MaxTokens int64 `json:"max_tokens"`
}

type AgentSkillBinding struct {
	// SkillID is the catalog key of the attached skill.
	SkillID string `json:"skill_id"`
	// Name is the operator-facing skill name.
	Name string `json:"name"`
	// Generated reports whether the skill was generated in-runtime
	// rather than imported.
	Generated bool `json:"generated"`
}

type AgentSkillsRequest struct {
	// Identity is the (tenant, user, session) scope. Mandatory.
	Identity IdentityScope `json:"identity"`
	// ID is the agent_id whose attached skills to list.
	ID string `json:"id"`
}

type AgentSkillsResponse struct {
	// AgentID echoes the requested agent_id.
	AgentID string `json:"agent_id"`
	// Skills is the agent's attached skills.
	Skills []AgentSkillBinding `json:"skills"`
}

type AgentStatus string

type AgentToolBinding struct {
	// ToolID is the catalog key of the bound tool.
	ToolID string `json:"tool_id"`
	// ToolName is the operator-facing tool name.
	ToolName string `json:"tool_name"`
	// Transport is the tool's transport ("in-proc" / "HTTP" / "MCP" /
	// "A2A" / "flow").
	Transport string `json:"transport"`
	// AuthStatus is the per-binding OAuth status: "no_auth" / "headers"
	// / "oauth_user_bound" / "oauth_agent_bound" / "oauth_expired".
	AuthStatus string `json:"auth_status"`
	// BindingScope is the OAuth binding scope (auth.BindingScope per):
	// "user" / "agent". Empty for a non-OAuth binding.
	BindingScope string `json:"binding_scope,omitempty"`
}

type AgentToolsRequest struct {
	// Identity is the (tenant, user, session) scope. Mandatory.
	Identity IdentityScope `json:"identity"`
	// ID is the agent_id whose tool bindings to list.
	ID string `json:"id"`
}

type AgentToolsResponse struct {
	// AgentID echoes the requested agent_id.
	AgentID string `json:"agent_id"`
	// Bindings is the agent's tool bindings.
	Bindings []AgentToolBinding `json:"bindings"`
}

type ArtifactRef struct {
	// ID is the content-addressed identifier
	// (`{namespace}_{sha256[:12]}`).
	ID string `json:"id"`
	// MimeType is the IANA media type, when known.
	MimeType string `json:"mime_type,omitempty"`
	// SizeBytes is the length of the referenced bytes.
	SizeBytes int64 `json:"size_bytes"`
	// Filename is metadata only — never used for path construction.
	Filename string `json:"filename,omitempty"`
	// SHA256 is the full hex digest of the referenced bytes.
	SHA256 string `json:"sha256,omitempty"`
	// Namespace is the logical bucket the artifact lives in.
	Namespace string `json:"namespace,omitempty"`
	// Scope is the artifact's owning identity scope.
	Scope ArtifactScope `json:"scope"`
}

type ArtifactRefSummary struct {
	// Filename is the artifact's display filename.
	Filename string `json:"filename"`
	// MIME is the artifact's content type.
	MIME string `json:"mime"`
	// SizeBytes is the artifact's byte size.
	SizeBytes int64 `json:"size_bytes"`
	// CreatedAt is when the artifact was produced.
	CreatedAt time.Time `json:"created_at"`
}

type ArtifactRow struct {
	// Ref is the canonical artifact reference.
	Ref ArtifactRef `json:"ref"`
	// Tags is the chip list assigned by the producing planner / tool.
	// Sourced from the storage-side `Source["tags"]` projection — never
	// promoted onto the storage ArtifactRef shape (open-question
	// resolution: project on the Protocol row, not the storage struct).
	Tags []string `json:"tags,omitempty"`
	// Source is the producer of the artifact — one of the four canonical
	// ArtifactSource values.
	Source ArtifactSource `json:"source,omitempty"`
	// Driver is the artifact store driver that holds this artifact —
	// "inmem" | "fs" | "sqlite" | "postgres" | "s3".
	Driver string `json:"driver,omitempty"`
	// CreatedAt is the artifact's put timestamp.
	CreatedAt time.Time `json:"created_at,omitempty"`
}

type ArtifactScope struct {
	// Tenant / User / Session are the mandatory isolation triple. An
	// empty component fails put / get_ref closed at the Protocol edge.
	Tenant  string `json:"tenant"`
	User    string `json:"user"`
	Session string `json:"session"`
	// Task is the per-task scope inside a session. Optional — empty for
	// session-scoped artifacts; a list filter treats an empty Task as a
	// wildcard.
	Task string `json:"task,omitempty"`
}

type ArtifactSource string

type ArtifactsDeleteRequest struct {
	// Scope is the artifact's isolation scope. The triple is mandatory.
	Scope ArtifactScope `json:"scope"`
	// ID is the content-addressed artifact id to evict.
	ID string `json:"id"`
}

type ArtifactsDeleteResponse struct {
	// Deleted reports whether the artifact existed before the delete.
	// Idempotent: deleting an absent artifact returns deleted=false with
	// no error (CodeNotFound is NOT raised — delete is a no-op-safe verb).
	Deleted bool `json:"deleted"`
	// ProtocolVersion echoes the Protocol version the Runtime answered
	// under so a client can detect a version skew.
	ProtocolVersion string `json:"protocol_version"`
}

type ArtifactsGetRefRequest struct {
	// Scope is the caller's identity scope. Tenant / User / Session are
	// mandatory.
	Scope ArtifactScope `json:"scope"`
	// ID is the content-addressed artifact identifier to resolve.
	ID string `json:"id"`
	// Expiry is the presigned-URL validity window. Defaults to
	// DefaultPresignExpiry (15m) when zero; values outside
	// [PresignExpiryMin, PresignExpiryMax] are rejected loudly.
	Expiry time.Duration `json:"expiry,omitempty"`
}

type ArtifactsGetRefResponse struct {
	// Ref is the artifact metadata reference.
	Ref ArtifactRef `json:"ref"`
	// PresignedURL is the time-bounded HTTPS URL the Console downloads
	// the bytes from directly, bypassing the runtime's bytes path.
	PresignedURL string `json:"presigned_url"`
	// ExpiresAt is the wall-clock instant the presigned URL stops being
	// valid.
	ExpiresAt time.Time `json:"expires_at"`
	// ProtocolVersion echoes the Protocol version.
	ProtocolVersion string `json:"protocol_version"`
}

type ArtifactsListRequest struct {
	// Scope is the caller's identity scope. A list filter treats empty
	// fields as wildcards; a Tenant differing from the caller's verified
	// tenant requires the admin scope per the closed admin-scope set.
	Scope ArtifactScope `json:"scope"`
	// MimeType is an OR-set of IANA media types. Empty == wildcard.
	MimeType []string `json:"mime_type,omitempty"`
	// Source is an OR-set of artifact producers. Empty == wildcard. An
	// unknown source value fails the request with CodeInvalidRequest.
	Source []ArtifactSource `json:"source,omitempty"`
	// SizeRange, when set, filters by stored byte size.
	SizeRange *SizeRange `json:"size_range,omitempty"`
	// CreatedRange, when set, filters by put timestamp.
	CreatedRange *TimeRange `json:"created_range,omitempty"`
	// Tags is an OR-set of tag strings. An artifact matches when it
	// carries at least one of the listed tags. Empty == wildcard.
	Tags []string `json:"tags,omitempty"`
	// Limit bounds the returned page. Defaults to DefaultArtifactsLimit
	// (100) when zero; values above MaxArtifactsLimit (1000) are clamped.
	Limit int `json:"limit,omitempty"`
}

type ArtifactsListResponse struct {
	// Rows is the page slice, at most Limit rows. Empty when the filter
	// matched nothing.
	Rows []ArtifactRow `json:"rows"`
	// TotalMatched is the count of rows matching the filter before the
	// Limit truncation — the Console paginator renders "N of M".
	TotalMatched int `json:"total_matched"`
	// ProtocolVersion echoes the Protocol version the Runtime answered
	// under so a client can detect a version skew.
	ProtocolVersion string `json:"protocol_version"`
}

type ArtifactsPutOpts struct {
	// MimeType is the IANA media type of the upload. Empty defaults to
	// the store's own default (text/plain for PutText-shaped bytes).
	MimeType string `json:"mime_type,omitempty"`
	// Filename is metadata only — never used for path construction.
	Filename string `json:"filename,omitempty"`
	// Namespace is the logical bucket the artifact lands in. Empty
	// defaults to "default" at the store.
	Namespace string `json:"namespace,omitempty"`
	// Source is the artifact producer. Defaults to ArtifactSourceUserUpload
	// when empty (an artifacts.put IS, by construction, a user upload).
	// An explicit unknown value fails the request with
	// CodeInvalidRequest.
	Source ArtifactSource `json:"source,omitempty"`
	// Tags is the chip list to assign to the artifact.
	Tags []string `json:"tags,omitempty"`
}

type ArtifactsPutRequest struct {
	// Scope is the caller's identity scope. Tenant / User / Session are
	// mandatory; a body whose Tenant disagrees with the caller's
	// verified tenant is rejected with CodeScopeMismatch.
	Scope ArtifactScope `json:"scope"`
	// Bytes is the artifact payload. JSON-encoded as a base64 string by
	// the standard []byte marshaller.
	Bytes []byte `json:"bytes"`
	// Opts is the optional upload metadata.
	Opts ArtifactsPutOpts `json:"opts,omitempty"`
}

type ArtifactsPutResponse struct {
	// Ref is the content-addressed reference to the stored artifact.
	Ref ArtifactRef `json:"ref"`
	// ProtocolVersion echoes the Protocol version.
	ProtocolVersion string `json:"protocol_version"`
}

type AuthRotateTokenRequest struct {
	// Identity is the caller's identity scope. The auth surface asserts
	// the triple against the verified JWT before re-minting.
	Identity IdentityScope `json:"identity"`
}

type AuthRotateTokenResponse struct {
	// NewToken is the re-minted Protocol-auth JWT, Bearer-shaped. The
	// operator copies this exactly once.
	NewToken string `json:"new_token"`
	// ExpiresAt is the new token's expiry, UTC.
	ExpiresAt time.Time `json:"expires_at"`
}

type Capability string

type ControlRequest struct {
	// Identity is the request's identity scope. The full quadruple
	// (triple + Run) is mandatory — a steering control targets a
	// specific run's inbox. Scope is the caller's steering scope claim.
	Identity IdentityScope `json:"identity"`
	// Payload is the method-specific control payload. May be nil — a
	// bare `cancel` / `pause` carries no payload. The steering
	// ValidatePayload enforces the RFC §6.3 bounds (depth ≤ 6, ≤ 64
	// keys, ≤ 50 list items, ≤ 4096 chars/string, ≤ 16 KiB total) at the
	// edge; an oversize payload fails the request closed.
	Payload map[string]any `json:"payload,omitempty"`
	// EventID is the caller-supplied idempotency / correlation key
	// (ULID-shaped). Optional — the control-history dedupe uses
	// it. Empty is permitted.
	EventID string `json:"event_id,omitempty"`
}

type ControlResponse struct {
	// Accepted is true when the control event was validated, scope-checked,
	// and enqueued on the run's steering inbox. A false Accepted is never
	// returned — a rejected control surfaces as a *protocol.Error from
	// Dispatch, not an Accepted=false response.
	Accepted bool `json:"accepted"`
	// Method echoes the Protocol method name the control was submitted
	// under (`cancel`, `pause`, …) so a client correlating async
	// responses can match them up.
	Method string `json:"method"`
	// ProtocolVersion echoes the Protocol version the Runtime answered
	// under so a client can detect a version skew.
	ProtocolVersion string `json:"protocol_version"`
}

type Deprecation struct {
	// Subject names the Protocol element being deprecated — the method
	// name, error code, `Type.Field` wire-field path, or capability
	// string, depending on Kind.
	Subject string `json:"subject"`
	// Kind classifies what Subject is — one of the DeprecationKind
	// constants.
	Kind DeprecationKind `json:"kind"`
	// DeprecatedIn is the Protocol version (a MAJOR.MINOR.PATCH string)
	// in which Subject was first marked deprecated.
	DeprecatedIn string `json:"deprecated_in"`
	// RemovedIn is the Protocol version in which Subject is removed. It
	// MUST sort strictly after DeprecatedIn — the span between the two
	// is the deprecation window.
	RemovedIn string `json:"removed_in"`
	// Replacement names the Protocol element callers should migrate to.
	// Optional — a deprecation with no replacement is a pure removal.
	Replacement string `json:"replacement,omitempty"`
	// Note is an optional human-readable migration hint.
	Note string `json:"note,omitempty"`
}

type DeprecationKind string

type EventAggregateRequest struct {
	// Identity is the (tenant, user, session) scope envelope every
	// Protocol client carries on the body. The aggregate handler pulls
	// the authoritative identity from the JWT / X-Harbor-* edge headers
	// (RFC §5.5) — this field is shape-only, declared so the body
	// decode's `DisallowUnknownFields` accepts the Console's standard
	// payload shape (`Transport.request` auto-injects `identity` on
	// every request body). Optional in the wire schema; ignored by the
	// handler. Before this field existed it was the only typed request
	// shape on the Console-facing surface that REFUSED the identity
	// envelope, breaking every Events page `events.aggregate` call
	// cross-origin.
	Identity IdentityScope `json:"identity,omitempty"`
	// Filter narrows the events the aggregator counts. The empty filter
	// (zero EventFilter) is interpreted as "every event in the caller's
	// own identity tuple" (per the EventFilter godoc).
	Filter EventFilter `json:"filter"`
	// Window is the inclusive lookback span. Must be > 0. The response
	// covers [Now-Window, Now) where Now is the runtime's clock at
	// handler entry.
	Window time.Duration `json:"window"`
	// Bucket is the per-bucket width. Must be > 0 and must evenly
	// divide Window (Window % Bucket == 0) — a non-dividing pair is
	// rejected with `CodeInvalidRequest` so the response's bucket count
	// is deterministic and a rendering client never sees a fractional
	// trailing bucket.
	Bucket time.Duration `json:"bucket"`
	// Anchor is the OPTIONAL origin of the bucket grid. When nil (the
	// default), the grid is anchored at the effective Now — the
	// response covers [Now-Window, Now) and a `bucket_start` is NOT
	// addressable twice (two calls at two instants return two boundary
	// sets). When set, bucket boundaries are floored onto the fixed grid
	// `Anchor + k·Bucket`: the response still covers a `Window`'s worth
	// of buckets, but aligned to that grid, so two calls at two instants
	// with the SAME Anchor + Window + Bucket share boundary instants — a
	// `bucket_start` is a stable coordinate a consumer can cache and
	// re-request, INCLUDING across a runtime restart and across two
	// fleet runtimes (the boundary is a pure function of Anchor+Bucket,
	// with no residual dependence on Now). Passing the Unix epoch
	// (`1970-01-01T00:00:00Z`) yields a globally-shared grid.
	//
	// It is a POINTER (not a `time.Time` value) because `omitempty` is a
	// no-op on a struct — a value type would always serialize the zero
	// time and break the additive/optional contract and its TS mirror.
	//
	// Grid-edge note: with an Anchor, the LAST bucket's `bucket_end` is
	// the grid boundary that covers Now — it is generally AFTER Now (by
	// up to one Bucket width), not equal to it. A rendering client must
	// therefore not treat the final bucket as "up to this instant"; the
	// grid re-phases the boundaries and never widens the read span by
	// more than one Bucket at either edge. UTC.
	Anchor *time.Time `json:"anchor,omitempty"`
	// ByTenant opts IN to per-tenant attribution on each bucket
	// (EventBucket.CountsByTenant). It is HONOURED ONLY on an
	// admin-widened read (a verified `admin` / `console:fleet` cross-
	// principal-or-multi-value fan-in, derived server-side); on any other
	// read it is IGNORED and the response is byte-identical to a request
	// that never set it (fail-closed — the body flag never elevates a
	// read, and never widens what is counted).
	//
	// When honoured, each bucket carries CountsByTenant re-projecting that
	// bucket's Counts by the counted events' existing tenant identity, so
	// the widened caller can independently verify the tenant boundary the
	// runtime enforced (the attribution keys must be a subset of the
	// tenants it asked for, and they must sum back to the totals). It adds
	// NO new identity axis and NO payload — a count per `(tenant,
	// event_type)` is the whole surface. Absent/false ⇒ no attribution.
	ByTenant bool `json:"by_tenant,omitempty"`
}

type EventAggregateResponse struct {
	// Buckets is the per-bucket count series, oldest first. Each
	// bucket's [Start, End) span is exactly `Request.Bucket` wide. When
	// the request carried no `Anchor`, the last bucket's End equals the
	// request's effective Now; when it carried an `Anchor`, the last
	// bucket's End is the grid boundary covering Now (generally AFTER
	// Now, by up to one Bucket — see EventAggregateRequest.Anchor).
	Buckets []EventBucket `json:"buckets"`
	// Truncated is true when the counts are PARTIAL: the aggregation could
	// not observe every matching event in the window. It is set UNIFORMLY
	// across drivers — a best-effort ring that has evicted matching events
	// (older matches may be lost) sets it, and a durable log whose window held more
	// matching events than the single-read aggregation bound could count
	// sets it too. It is the honest DATA signal that a driver difference
	// (retention depth, an observed horizon) changed WHAT the method
	// returns without ever changing WHETHER it works: an over-wide window is
	// never a request error and never a silent undercount — it is partial
	// buckets flagged truncated. False means the counts are complete for the
	// window.
	Truncated bool `json:"truncated,omitempty"`
	// ProtocolVersion echoes the Protocol version the Runtime answered
	// under so a client can detect a version skew (mirrors the
	// ControlResponse / StartResponse shape).
	ProtocolVersion string `json:"protocol_version"`
}

type EventBucket struct {
	// Start is the bucket's lower bound (inclusive). UTC. The JSON tag
	// is namespaced (bucket_start rather than start) so the wire
	// surface does not collide with the task-control method
	// name start — the single-source grep backstop is
	// substring-shaped (it does not parse struct tags) and a bare
	// start tag would false-positive against it.
	Start time.Time `json:"bucket_start"`
	// End is the bucket's upper bound (exclusive). UTC. End - Start ==
	// the request's `Bucket` width.
	End time.Time `json:"bucket_end"`
	// Counts maps event-type string → count of events in this bucket.
	// An empty map means "no matching events in this window slice" —
	// the bucket is still present so the rendering client sees the gap.
	Counts map[string]int64 `json:"counts"`
	// CountsByTenant is the OPTIONAL per-tenant attribution of this
	// bucket's Counts: tenant → event-type → count. It is present ONLY
	// when the request set ByTenant AND the read was admin-widened (a
	// verified `admin` / `console:fleet` fan-in, derived server-side —
	// never from the request body). Absent (nil, omitted) on every other
	// read, so a caller that does not opt in sees a byte-identical
	// response.
	//
	// It is a pure re-projection of the SAME counted events by their
	// existing tenant identity — no new data path, no new identity axis.
	// The keys are a SUBSET of the authorized (named-or-folded)
	// Filter.TenantIDs; Counts (the totals) and CountsByTenant are scoped
	// to the IDENTICAL authorized filter by construction (one pass over
	// the same matched events), so per bucket
	// `Σ_tenant CountsByTenant[tenant][type] == Counts[type]`. That
	// reconciliation is what makes the tenant boundary independently
	// verifiable on an aggregate the way it already is on a row read
	// (every row carries its own tenant): the widened caller can check the
	// attribution keys against the entitled set it asked for.
	//
	// Empty buckets (no matching events) omit the field even under an
	// attribution request — there is nothing to attribute.
	CountsByTenant map[string]map[string]int64 `json:"counts_by_tenant,omitempty"`
}

type EventFilter struct {
	// EventTypes narrows to events whose `Type` is in the set. Empty
	// matches every type (today's `events.subscribe` default). The
	// strings are the registered `events.EventType` values
	// (`tool.failed`, `planner.repair_exhausted`, etc.).
	EventTypes []string `json:"event_types,omitempty"`
	// TenantIDs / UserIDs / SessionIDs / RunIDs narrow to events whose
	// identity tuple matches one of the supplied values. Empty on any
	// axis is interpreted as "the caller's own component"; >1 on the
	// tenant axis (or a single tenant other than the caller's) requires
	// `auth.ScopeAdmin` OR `auth.ScopeConsoleFleet` per the closed admin-scope set.
	TenantIDs  []string `json:"tenant_ids,omitempty"`
	UserIDs    []string `json:"user_ids,omitempty"`
	SessionIDs []string `json:"session_ids,omitempty"`
	RunIDs     []string `json:"run_ids,omitempty"`
	// Since is the optional lower bound (inclusive) on `OccurredAt`.
	// Zero means "unbounded on the lower side." UTC.
	Since time.Time `json:"since,omitempty"`
	// Until is the optional upper bound (exclusive) on `OccurredAt`.
	// Zero means "unbounded on the upper side." UTC.
	Until time.Time `json:"until,omitempty"`
}

type EventsListRequest struct {
	// Identity is the (tenant, user, session) scope envelope every
	// Protocol client carries on the body. The handler pulls the
	// authoritative identity from the JWT / X-Harbor-* edge headers
	// (RFC §5.5) — this field is shape-only, declared so the body decode's
	// `DisallowUnknownFields` accepts the Console's standard payload shape
	// (`Transport.request` auto-injects `identity` on every request body).
	// Optional in the wire schema; ignored by the handler.
	Identity IdentityScope `json:"identity,omitempty"`
	// Filter narrows the events returned. The empty filter (zero
	// EventFilter) is interpreted as "every event in the caller's own
	// identity tuple" (per the EventFilter godoc). A cross-tenant filter
	// (a tenant other than the caller's, or multiple tenants) requires the
	// verified `admin` OR `console:fleet` claim per the closed admin-scope
	// set; scope is derived server-side, never from this body.
	Filter EventFilter `json:"filter"`
	// Cursor is the exclusive upper sequence bound (the scroll-up cursor):
	// only events with Sequence < Cursor are returned. Zero means "from the
	// tail" (the newest retained events). To scroll one page older, pass the
	// prior response's NextCursor back here.
	Cursor uint64 `json:"cursor,omitempty"`
	// Limit is the page size K (clamped to MaxEventsListLimit;
	// zero ⇒ DefaultEventsListLimit).
	Limit int `json:"limit,omitempty"`
}

type EventsListResponse struct {
	// Events is the page's events, oldest-first within the window.
	Events []StateEvent `json:"events"`
	// NextCursor is the lowest Sequence in this page — the value to pass
	// back as Cursor to scroll one page older. Zero when the retained head
	// is reached (no older events).
	NextCursor uint64 `json:"next_cursor"`
	// HasMore reports whether older matching events remain before the
	// page's oldest event.
	HasMore bool `json:"has_more"`
	// Truncated is true when the substrate's oldest retained row sits above
	// the true first matching event (a best-effort ring evicted older
	// events) — the honest gap signal, never a silent drop. False on the
	// gap-free durable log.
	Truncated bool `json:"truncated,omitempty"`
}

type Flow struct {
	// ID is the flow's stable identifier — the registered flow name.
	ID string `json:"id"`
	// Name is the operator-facing display name. Equal to ID at V1; the
	// field exists so a future rename surface does not break the wire.
	Name string `json:"name"`
	// Owner is the flow's declared owner (the agent / team that
	// registered it). Empty when the registration carried no owner.
	Owner string `json:"owner,omitempty"`
	// Version is the flow's version string. Empty when unversioned.
	Version string `json:"version,omitempty"`
	// PlannerFamily is the graph-family planner the flow runs on —
	// "graph" / "workflow" / "deterministic". The catalog is filtered
	// to graph-family planners.
	PlannerFamily string `json:"planner_family,omitempty"`
	// NodeCount is the number of nodes in the flow's engine graph.
	NodeCount int `json:"node_count"`
	// EdgeCount is the number of directed edges in the flow's graph.
	EdgeCount int `json:"edge_count"`
	// Runs24h is the count of invocations in the trailing 24h window
	// scoped to the caller's identity (admin fans across tenants).
	Runs24h int64 `json:"runs_24h"`
	// P50LatencyMS is the median run latency over the window, in ms.
	P50LatencyMS int64 `json:"p50_latency_ms"`
	// P95LatencyMS is the 95th-percentile run latency over the window.
	P95LatencyMS int64 `json:"p95_latency_ms"`
	// SuccessRate is the fraction of runs in the window that succeeded,
	// in [0,1].
	SuccessRate float64 `json:"success_rate"`
	// LastRun is the wall-clock time of the most recent invocation. The
	// zero value (omitted) means the flow has never run.
	LastRun time.Time `json:"last_run,omitempty"`
	// Budget is the flow's per-flow Budget. Read-only at V1.
	Budget FlowBudget `json:"budget"`
}

type FlowArtifactRef struct {
	// ID is the content-addressed identifier.
	ID string `json:"id"`
	// MimeType is the IANA media type, when known.
	MimeType string `json:"mime_type,omitempty"`
	// SizeBytes is the length of the referenced bytes.
	SizeBytes int64 `json:"size_bytes,omitempty"`
	// Filename is metadata only (never used for path construction).
	Filename string `json:"filename,omitempty"`
	// SHA256 is the full hex digest of the referenced bytes.
	SHA256 string `json:"sha256,omitempty"`
}

type FlowBudget struct {
	// DeadlineMS is the flow's wall-clock deadline in milliseconds. Zero
	// means "no deadline cap".
	DeadlineMS int64 `json:"deadline_ms,omitempty"`
	// RequestCap is the flow's hop budget — the maximum number of node
	// hops a single invocation may take. Zero means "no hop cap".
	RequestCap int `json:"request_cap,omitempty"`
	// CostCapUSD is the flow's aggregate cost cap in US dollars. Zero
	// means "no cost cap".
	CostCapUSD float64 `json:"cost_cap_usd,omitempty"`
	// TokenCap is the flow's aggregate token cap. Zero means "no token
	// cap". The token cap is a post-V1 axis on the runtime `Budget`;
	// the field exists on the wire so the Budget meter can render it
	// without a wire-shape break when the axis lands.
	TokenCap int64 `json:"token_cap,omitempty"`
}

type FlowBudgetConsumption struct {
	// RequestsUsed is the hop count consumed in the active window.
	RequestsUsed int `json:"requests_used"`
	// CostUSDUsed is the cost consumed in the active window.
	CostUSDUsed float64 `json:"cost_usd_used"`
	// TokensUsed is the token count consumed in the active window.
	TokensUsed int64 `json:"tokens_used"`
}

type FlowDescribeRequest struct {
	// Identity is the mandatory caller identity scope.
	Identity IdentityScope `json:"identity"`
	// ID is the flow to describe. An unknown id fails with CodeNotFound.
	ID string `json:"id"`
}

type FlowDescription struct {
	// Flow is the catalog row for the described flow.
	Flow Flow `json:"flow"`
	// Nodes is the flow's node set, sorted lexicographically by ID.
	Nodes []FlowNode `json:"nodes"`
	// Edges is the flow's directed edge set, sorted by (From, To).
	Edges []FlowEdge `json:"edges"`
	// Source is the source-of-truth reference — a Go path or YAML
	// descriptor path. A string reference, never executable code.
	Source string `json:"source,omitempty"`
	// BudgetConsumption is the flow's live Budget consumption over the
	// active window — the data the Budget meter renders.
	BudgetConsumption FlowBudgetConsumption `json:"budget_consumption"`
}

type FlowEdge struct {
	// From is the upstream node's ID.
	From string `json:"from"`
	// To is the downstream node's ID.
	To string `json:"to"`
}

type FlowFilter struct {
	// Tenants restricts the catalog to the named tenants. Empty means
	// "the caller's own tenant". A value reaching outside the caller's
	// tenant requires the admin scope claim.
	Tenants []string `json:"tenants,omitempty"`
	// PlannerFamilies restricts the catalog to the named planner
	// families. Empty means "all graph-family planners".
	PlannerFamilies []string `json:"planner_families,omitempty"`
	// Query is a free-text substring match over the flow name / owner.
	// Empty means "no text filter".
	Query string `json:"query,omitempty"`
}

type FlowListRequest struct {
	// Identity is the mandatory caller identity scope. An incomplete
	// triple fails the request closed with CodeIdentityRequired.
	Identity IdentityScope `json:"identity"`
	// Filter narrows the catalog. The zero value lists the caller's
	// own-tenant flows.
	Filter FlowFilter `json:"filter"`
	// Page is the 1-based page index. Zero is treated as page 1.
	Page int `json:"page,omitempty"`
	// PageSize is the per-page row count. Zero applies
	// DefaultFlowListPageSize; a value above MaxFlowListPageSize is
	// rejected with CodeInvalidRequest.
	PageSize int `json:"page_size,omitempty"`
}

type FlowListResponse struct {
	// Flows is the catalog page, sorted lexicographically by ID for
	// byte-stability across requests.
	Flows []Flow `json:"flows"`
	// Page is the 1-based page index this response covers.
	Page int `json:"page"`
	// PageSize is the per-page row count applied.
	PageSize int `json:"page_size"`
	// PageCount is the total number of pages for the filtered set.
	PageCount int `json:"page_count"`
	// TotalRows is the total number of catalog rows the filter matched
	// before pagination.
	TotalRows int `json:"total_rows"`
}

type FlowMetrics struct {
	// FlowID is the flow these metrics describe.
	FlowID string `json:"flow_id"`
	// WindowStart is the wall-clock start of the aggregation window.
	WindowStart time.Time `json:"window_start"`
	// WindowEnd is the wall-clock end of the aggregation window.
	WindowEnd time.Time `json:"window_end"`
	// Buckets are the time-bucketed aggregates, oldest first.
	Buckets []FlowMetricsBucket `json:"buckets"`
	// BudgetConsumption is the flow's live Budget consumption over the
	// window — the data the budget sparkline renders.
	BudgetConsumption FlowBudgetConsumption `json:"budget_consumption"`
}

type FlowMetricsBucket struct {
	// BucketStart is the wall-clock start of the bucket.
	BucketStart time.Time `json:"bucket_start"`
	// Runs is the count of runs that started within the bucket.
	Runs int64 `json:"runs"`
	// P95LatencyMS is the 95th-percentile run latency within the bucket.
	P95LatencyMS int64 `json:"p95_latency_ms"`
	// SuccessRate is the fraction of bucketed runs that succeeded.
	SuccessRate float64 `json:"success_rate"`
	// CostUSD is the total cost recorded within the bucket.
	CostUSD float64 `json:"cost_usd"`
}

type FlowMetricsRequest struct {
	// Identity is the mandatory caller identity scope.
	Identity IdentityScope `json:"identity"`
	// FlowID is the flow whose metrics to aggregate. An empty FlowID
	// fails with CodeInvalidRequest.
	FlowID string `json:"flow_id"`
	// WindowMS is the aggregation window in milliseconds. Zero applies
	// the default 24h window.
	WindowMS int64 `json:"window_ms,omitempty"`
	// BucketMS is the bucket width in milliseconds. Zero applies the
	// default 1h bucket.
	BucketMS int64 `json:"bucket_ms,omitempty"`
}

type FlowNode struct {
	// ID is the node's unique identifier within the flow.
	ID string `json:"id"`
	// Type is the node's role tag — subflow / tool / pause /
	// artifact_emitter.
	Type FlowNodeKind `json:"type"`
	// Descriptor is a schema reference for the node — the tool name for
	// a tool node, the nested flow id for a subflow node. It is a string
	// reference, never executable code.
	Descriptor string `json:"descriptor,omitempty"`
	// Policy is the node's per-node policy. Nil when the node carries
	// the engine default policy.
	Policy *FlowNodePolicy `json:"policy,omitempty"`
}

type FlowNodeKind string

type FlowNodePolicy struct {
	// MaxRetries is the per-node retry ceiling.
	MaxRetries int `json:"max_retries,omitempty"`
	// TimeoutMS is the per-node wall-clock timeout in milliseconds.
	TimeoutMS int64 `json:"timeout_ms,omitempty"`
}

type FlowNodeRunState struct {
	// NodeID is the node's identifier within the flow.
	NodeID string `json:"node_id"`
	// Status is the node's outcome within the run.
	Status FlowRunStatus `json:"status"`
	// DurationMS is the node's wall-clock duration in milliseconds.
	DurationMS int64 `json:"duration_ms,omitempty"`
	// Retries is the number of times the node was retried.
	Retries int `json:"retries,omitempty"`
	// ErrorClass is a short classification of a node failure. Empty for
	// a non-failed node.
	ErrorClass string `json:"error_class,omitempty"`
}

type FlowRun struct {
	// RunID is the run's stable identifier.
	RunID string `json:"run_id"`
	// FlowID is the flow this run executed.
	FlowID string `json:"flow_id"`
	// Status is the run's outcome.
	Status FlowRunStatus `json:"status"`
	// Trigger is what initiated the run.
	Trigger FlowRunTrigger `json:"trigger"`
	// StartedAt is the wall-clock time the run started.
	StartedAt time.Time `json:"started_at"`
	// DurationMS is the run's wall-clock duration in milliseconds. Zero
	// for a run still in flight.
	DurationMS int64 `json:"duration_ms,omitempty"`
	// CostUSD is the run's recorded cost in US dollars.
	CostUSD float64 `json:"cost_usd,omitempty"`
	// Identity is the (tenant, user, session) the run executed under.
	Identity IdentityScope `json:"identity"`
	// ErrorClass is a short classification of the failure for a failed
	// run. Empty for a non-failed run.
	ErrorClass string `json:"error_class,omitempty"`
}

type FlowRunDescribeRequest struct {
	// Identity is the mandatory caller identity scope.
	Identity IdentityScope `json:"identity"`
	// RunID is the run to describe. An unknown id fails with
	// CodeNotFound.
	RunID string `json:"run_id"`
}

type FlowRunDescription struct {
	// Run is the run-history row for the described run.
	Run FlowRun `json:"run"`
	// NodeStates is the per-node execution timeline, in node order.
	NodeStates []FlowNodeRunState `json:"node_states"`
	// OutputPreview is the run's final output INLINE when its serialised
	// size is below the heavy-content threshold. Empty when the run
	// produced no output or when the output was routed by-reference.
	OutputPreview string `json:"output_preview,omitempty"`
	// OutputRef is populated when the run's final output exceeded the
	// heavy-content threshold. The Console fetches the bytes via
	// `artifacts.get` when it wants them. When OutputRef is set,
	// OutputPreview is empty.
	OutputRef *FlowArtifactRef `json:"output_ref,omitempty"`
}

type FlowRunRequest struct {
	// Identity is the mandatory caller identity scope.
	Identity IdentityScope `json:"identity"`
	// FlowID is the flow to invoke. An empty / unknown id fails with
	// CodeInvalidRequest / CodeNotFound.
	FlowID string `json:"flow_id"`
	// Inputs is the hand-crafted input form for the invocation. The
	// runtime validates it against the flow's input schema.
	Inputs map[string]any `json:"inputs,omitempty"`
}

type FlowRunResponse struct {
	// RunID is the identifier of the accepted run.
	RunID string `json:"run_id"`
	// Status is the run's status at acceptance — "running" for an
	// accepted run.
	Status FlowRunStatus `json:"status"`
	// StartedAt is the wall-clock time the run started.
	StartedAt time.Time `json:"started_at"`
}

type FlowRunStatus string

type FlowRunTrigger string

type FlowRunsListRequest struct {
	// Identity is the mandatory caller identity scope.
	Identity IdentityScope `json:"identity"`
	// FlowID is the flow whose run history to list. An empty FlowID
	// fails with CodeInvalidRequest.
	FlowID string `json:"flow_id"`
	// Tenants restricts the history to the named tenants. Empty means
	// "the caller's own tenant". A value reaching outside the caller's
	// tenant requires the admin scope claim.
	Tenants []string `json:"tenants,omitempty"`
	// Page is the 1-based page index. Zero is treated as page 1.
	Page int `json:"page,omitempty"`
	// PageSize is the per-page row count. Zero applies
	// DefaultFlowListPageSize.
	PageSize int `json:"page_size,omitempty"`
	// Since is an optional lower bound on a run's StartedAt (zero =
	// unbounded). The bound is INCLUSIVE: a run whose StartedAt equals
	// Since is retained. It mirrors TaskFilter.Since/Until exactly — same
	// field shape AND same inclusive boundary semantics — so every list
	// method behaves identically on a time boundary. Absent ⇒ unbounded
	// (zero behaviour change for existing callers). Bounds apply on the
	// server, BEFORE pagination — the page counts reflect the bounded
	// set, never a client-side walk-and-filter.
	Since time.Time `json:"since,omitempty"`
	// Until is an optional upper bound on a run's StartedAt (zero =
	// unbounded). The bound is INCLUSIVE: a run whose StartedAt equals
	// Until is retained, matching TaskFilter.Until and the sessions
	// started-window (a closed window [Since, Until]). A request whose
	// Until precedes its Since fails CodeInvalidRequest (the same
	// validation posture the task-list filter holds). Absent ⇒ unbounded.
	Until time.Time `json:"until,omitempty"`
}

type FlowRunsListResponse struct {
	// Runs is the run-history page, sorted by StartedAt descending
	// (newest first).
	Runs []FlowRun `json:"runs"`
	// Page is the 1-based page index this response covers.
	Page int `json:"page"`
	// PageSize is the per-page row count applied.
	PageSize int `json:"page_size"`
	// PageCount is the total number of pages.
	PageCount int `json:"page_count"`
	// TotalRows is the total number of run rows the filter matched.
	TotalRows int `json:"total_rows"`
}

type GovernanceGetTenantOverridesRequest struct {
	// Identity is the request's identity scope. The triple is mandatory;
	// the admin scope is required (reading a tenant's control-plane
	// defaults is a privileged action).
	Identity IdentityScope `json:"identity"`
}

type GovernanceGetTenantOverridesResponse struct {
	// Overrides is the tenant's current default-override record. When no
	// record exists (Set is false) every field is nil.
	Overrides GovernanceTenantOverrides `json:"overrides"`
	// Set reports whether a tenant-default record exists. False means the
	// tenant inherits every runtime config default.
	Set bool `json:"set"`
	// ProtocolVersion echoes the Protocol version the Runtime answered
	// with.
	ProtocolVersion string `json:"protocol_version"`
}

type GovernancePostureRequest struct {
	// TenantID — empty = the caller's own tenant; non-empty + different
	// from the caller's resolved tenant = requires auth.ScopeAdmin.
	TenantID string `json:"tenant_id,omitempty"`
}

type GovernancePostureResponse struct {
	// DefaultTier is the operator-configured default tier name applied
	// to an identity that does not match a custom resolver mapping.
	// Empty when no tiers are configured.
	DefaultTier string `json:"default_tier"`
	// ResolvedTier is the tier name the caller's identity resolves to
	// via the runtime's configured TierResolver. Empty when no tier
	// resolves (latent default).
	ResolvedTier string `json:"resolved_tier"`
	// IdentityTiers maps tier name → tier configuration (the consolidated
	// shape). Always non-nil; an empty map signals no enforcement.
	IdentityTiers map[string]IdentityTierView `json:"identity_tiers"`
	// ProtocolVersion echoes the Protocol version the Runtime answered
	// with — same field every Protocol response carries.
	ProtocolVersion string `json:"protocol_version"`
}

type GovernanceRotateKeyRequest struct {
	// Identity is the request's identity scope. The triple is mandatory;
	// the admin scope is required (rotating a provider credential is a
	// privileged action).
	Identity IdentityScope `json:"identity"`
	// Provider names the provider whose key to rotate. Empty targets the
	// runtime's bound provider (the common single-provider case); a value
	// other than the bound provider is rejected with CodeInvalidRequest
	// (multi-provider rotation is post-V1).
	Provider string `json:"provider,omitempty"`
	// Key is the new API key value. MANDATORY and a SECRET — it travels
	// only on this request leg, is held only in the runtime's atomic key
	// holder, and is NEVER logged, audited, or echoed back. An empty Key
	// is rejected with CodeInvalidRequest before any swap.
	Key string `json:"key"`
}

type GovernanceRotateKeyResponse struct {
	// Provider is the provider whose key was rotated.
	Provider string `json:"provider"`
	// Fingerprint is a non-reversible digest of the new key
	// (`sha256:<prefix>`) — correlatable, never the secret.
	Fingerprint string `json:"fingerprint"`
	// RotatedAt is the runtime timestamp at which the key was swapped. The
	// new key is effective immediately (the next call uses it).
	RotatedAt time.Time `json:"rotated_at"`
	// ProtocolVersion echoes the Protocol version the Runtime answered
	// with.
	ProtocolVersion string `json:"protocol_version"`
}

type GovernanceSetPostureRequest struct {
	// DefaultTier is the default-tier assignment applied to an identity
	// that resolves to no explicit tier. Required — an empty value is
	// rejected when any tier is enforced.
	DefaultTier string `json:"default_tier"`
	// IdentityTiers is the complete tier table keyed by tier name. A tier
	// present in the current effective policy but ABSENT here — or present
	// with a zeroed enforced ceiling — is a fail-closed rejection, not a
	// silent widening. Always keyed by tier name; the value is the read's
	// `IdentityTierView` projection.
	IdentityTiers map[string]IdentityTierView `json:"identity_tiers"`
}

type GovernanceSetPostureResponse struct {
	// DefaultTier is the persisted default-tier assignment.
	DefaultTier string `json:"default_tier"`
	// IdentityTiers is the persisted tier table (the full-replace result).
	// Always non-nil in the wire JSON (`{}`, never `null`).
	IdentityTiers map[string]IdentityTierView `json:"identity_tiers"`
	// EnforcementPendingRestart reports an honest degradation: the policy was
	// persisted and will be enforced, but this runtime booted fully latent (no
	// config tiers AND no prior record) so it composed no governance wrapper —
	// the new policy therefore does NOT enforce until the next restart (which
	// seeds a wrapper from the now-persisted record). False on a runtime that
	// booted with an active governance wrapper (the common case): the write
	// enforces on the next call. Additive field — omitted (false) is the
	// enforce-immediately posture.
	EnforcementPendingRestart bool `json:"enforcement_pending_restart"`
	// ProtocolVersion echoes the Protocol version the Runtime answered
	// with, so a Console can assert wire compatibility.
	ProtocolVersion string `json:"protocol_version"`
}

type GovernanceSetTenantOverridesRequest struct {
	// Identity is the request's identity scope. The triple is mandatory.
	// The runtime requires the admin scope claim and rejects a non-admin
	// caller with CodeScopeMismatch.
	Identity IdentityScope `json:"identity"`
	// Overrides is the desired-state override record (a full REPLACE of
	// the tenant's prior record).
	Overrides GovernanceTenantOverrides `json:"overrides"`
}

type GovernanceSetTenantOverridesResponse struct {
	// AppliedAt is the runtime timestamp at which the tenant default was
	// persisted. The new default takes effect on each session's next run.
	AppliedAt time.Time `json:"applied_at"`
	// ProtocolVersion echoes the Protocol version the Runtime answered
	// with, so a Console can assert wire compatibility.
	ProtocolVersion string `json:"protocol_version"`
}

type GovernanceTenantOverrides struct {
	// Model, when non-nil, overrides the default model name. The runtime
	// validates it against the configured ModelProfiles at set time and
	// rejects an unknown model with CodeInvalidRequest.
	Model *string `json:"model,omitempty"`
	// ExtraInstructions, when non-nil, is an ADDITIVE block appended to
	// the agent's system prompt (rendered into the additional-guidance
	// section). It extends the prompt; it never replaces it. nil means
	// "no extension."
	ExtraInstructions *string `json:"extra_instructions,omitempty"`
	// Temperature, when non-nil, overrides the sampling temperature. The
	// runtime rejects a value outside the closed range [0, 2] with
	// CodeInvalidRequest.
	Temperature *float64 `json:"temperature,omitempty"`
	// MaxTokens, when non-nil, overrides the per-call token ceiling. The
	// runtime rejects a non-positive value with CodeInvalidRequest.
	MaxTokens *int `json:"max_tokens,omitempty"`
	// ReasoningEffort, when non-nil, overrides the reasoning-effort hint.
	// The runtime rejects a value outside {low, medium, high} with
	// CodeInvalidRequest.
	ReasoningEffort *string `json:"reasoning_effort,omitempty"`
}

type HistogramBucket struct {
	// UpperBound is the inclusive upper bound of the bucket.
	UpperBound float64 `json:"upper_bound"`
	// Count is the cumulative observation count at or below
	// UpperBound.
	Count uint64 `json:"count"`
}

type IdentityScope struct {
	// Tenant / User / Session are the mandatory isolation triple. An
	// empty component fails the request closed at the Protocol edge.
	// When impersonation is in use, these fields carry the IMPERSONATED
	// identity — the identity the run executes under (matches the
	// Impersonating triple component-for-component).
	Tenant  string `json:"tenant"`
	User    string `json:"user"`
	Session string `json:"session"`
	// Run is the per-execution scope inside a session. Mandatory for the
	// nine steering-control methods (they target a specific run's inbox);
	// optional for `start` (a `start` request mints a new run / task, so
	// it carries no pre-existing run id).
	Run string `json:"run,omitempty"`
	// Scope is the caller's steering scope claim — one of the three
	// canonical steering scopes (`session_user` / `owner_user` /
	// `admin`). It is trust-based until a later phase Protocol auth, exactly
	// as `events.Filter.Admin` is; the ControlSurface enforces the
	// per-method scope via the steering CheckScope. Ignored for
	// `start` (task creation is not a steering control).
	Scope string `json:"scope,omitempty"`

	// Actor is the verified admin identity at the request edge — the
	// identity whose JWT claim was validated by the middleware.
	// V1 invariant: Actor MUST equal the JWT's verified `(tenant, user,
	// session)` triple; the transport rejects a body claiming a different
	// Actor with CodeScopeMismatch. The Actor's audit trail ("admin X
	// impersonated user Y at time T") is what makes impersonation
	// accountable.
	Actor *IdentityScope `json:"actor,omitempty"`

	// Requester is the originating admin identity for delegated
	// impersonation chains (e.g. an admin acting on behalf of another
	// admin's audited request). At V1: Requester MUST equal Actor; the
	// field exists so post-V1 delegated impersonation does not require a
	// wire-shape break. The runtime rejects Requester != Actor with
	// CodeScopeMismatch.
	Requester *IdentityScope `json:"requester,omitempty"`

	// Impersonating is the target identity the run executes under. When
	// non-empty, MUST carry a complete `(tenant, user, session)` triple —
	// identity is mandatory; the impersonated triple is identity too.
	// Setting Impersonating gates on auth.ScopeAdmin on the verified JWT;
	// a non-admin request with Impersonating set is rejected with
	// CodeScopeMismatch before Dispatch runs.
	//
	// V1 semantics: the top-level Tenant/User/Session fields MUST equal
	// the Impersonating triple when impersonation is in use — the run
	// executes as the impersonated identity. The Actor field carries the
	// audit-visible record of WHO impersonated.
	Impersonating *IdentityScope `json:"impersonating,omitempty"`
}

type IdentityTierView struct {
	// BudgetCeilingUSD is the per-identity (per tier) cost ceiling in
	// USD. 0 = no ceiling.
	BudgetCeilingUSD float64 `json:"budget_ceiling_usd"`
	// RateLimit is the per-(identity, model) token-bucket configuration.
	RateLimit RateLimitView `json:"rate_limit"`
	// MaxTokens is the per-call MaxTokens cap. 0 = no enforcement.
	MaxTokens int `json:"max_tokens"`
}

type InterventionSummary struct {
	// Type is the intervention kind — a HITL pause, a tool-approval
	// gate, or a tool-OAuth gate.
	Type string `json:"type"`
	// Reason is the operator-facing reason the intervention fired.
	Reason string `json:"reason"`
	// Outcome is the intervention's resolution — pending, resolved,
	// approved, or rejected.
	Outcome string `json:"outcome"`
	// OccurredAt is when the intervention fired.
	OccurredAt time.Time `json:"occurred_at"`
}

type LLMPostureRequest struct {
	// TenantID — empty = the caller's own tenant; non-empty + different
	// from the caller's resolved tenant = requires auth.ScopeAdmin.
	TenantID string `json:"tenant_id,omitempty"`
}

type LLMPostureResponse struct {
	// Provider is the LLM provider name (e.g. "bifrost", "mock").
	Provider string `json:"provider"`
	// Model is the bound model identifier (e.g. "openai/gpt-5.3-chat").
	Model string `json:"model"`
	// Region is the provider endpoint region; "" when not applicable
	// (the Console renders an em-dash placeholder for the empty case).
	Region string `json:"region"`
	// MockMode is true iff the runtime booted with HARBOR_DEV_ALLOW_MOCK=1.
	// The Console renders the canonical
	// `[DEV-ONLY MOCK LLM — DO NOT USE IN PRODUCTION]` banner when this
	// is true; hiding the banner is a §13 forbidden-practice violation.
	MockMode bool `json:"mock_mode"`
	// ProtocolVersion echoes the Protocol version the Runtime answered
	// with — same field every Protocol response carries.
	ProtocolVersion string `json:"protocol_version"`
}

type MCPAppCallToolRequest struct {
	// Identity is the (tenant, user, session) scope the tool call runs
	// under. Mandatory — an incomplete triple fails closed.
	Identity IdentityScope `json:"identity"`
	// Tool is the catalog tool name to invoke (the Harbor-side
	// `<source>_<tool>` name).
	Tool string `json:"tool"`
	// Arguments is the raw JSON argument object the tool's schema
	// validates on the wire.
	Arguments json.RawMessage `json:"arguments,omitempty"`
}

type MCPAppCallToolResponse struct {
	// Tool echoes the invoked tool name.
	Tool string `json:"tool"`
	// Content is the inline tool-result JSON, populated ONLY when the
	// encoded result is below the heavy-content threshold. Empty when
	// ArtifactRef is set.
	Content json.RawMessage `json:"content,omitempty"`
	// ArtifactRef is the by-reference stub, populated when the encoded
	// result meets or exceeds the heavy-content threshold. Nil when
	// Content is set.
	ArtifactRef *MCPResourceArtifactRef `json:"artifact_ref,omitempty"`
	// IsError reports whether the MCP server returned a tool error
	// (the result's IsError flag) — the app renders it as a failure.
	IsError bool `json:"is_error"`
	// App is the MCP App reference parsed from the tool result's
	// `_meta.ui.resourceUri`, or nil for a non-app result.
	App *MCPAppRef `json:"app,omitempty"`
	// ProtocolVersion echoes the Protocol version the Runtime answered
	// under so a client can detect a version skew.
	ProtocolVersion string `json:"protocol_version"`
}

type MCPAppRef struct {
	// ServerID is the MCP server (source id) hosting the app's UI document
	// and tools. The Console pairs it with ResourceURI to fetch the
	// document via mcp.servers.read_resource — without it the renderer
	// cannot resolve which server to read from. Empty for a non-app result.
	ServerID string `json:"server_id,omitempty"`
	// ToolCallID is the stable per-invocation id of the tool call that
	// declared the app. The Console pairs it with ServerID to fetch the
	// tool context (input + lowered result) via mcp.apps.tool_context.
	// Empty for a non-app result.
	ToolCallID string `json:"tool_call_id,omitempty"`
	// ResourceURI is the `ui://`-scheme URI of the app's UI document.
	// The Console fetches the document via mcp.servers.read_resource.
	ResourceURI string `json:"resource_uri"`
	// DisplayMode is the negotiated MCP-Apps display mode for this
	// result (one of inline / fullscreen / pip), or empty when the
	// server stated no preference and none was negotiated.
	DisplayMode string `json:"display_mode,omitempty"`
	// RawHTMLTrusted reports the per-server raw-HTML trust flag — the
	// default-deny posture means the host sandboxes the iframe unless an
	// operator explicitly opted in (mcp.servers.set_raw_html_trust).
	RawHTMLTrusted bool `json:"raw_html_trusted"`
}

type MCPAuthorizationServerView struct {
	// Issuer is the authorization server's issuer identifier.
	Issuer string `json:"issuer"`
	// AuthorizationEndpoint is the RFC 6749 authorization endpoint URL.
	AuthorizationEndpoint string `json:"authorization_endpoint"`
	// TokenEndpoint is the RFC 6749 token endpoint URL. NEVER dialed by Harbor.
	TokenEndpoint string `json:"token_endpoint"`
	// ScopesSupported is the advertised scope list. Always non-nil.
	ScopesSupported []string `json:"scopes_supported"`
	// CodeChallengeMethodsSupported is the advertised PKCE method list. Always
	// non-nil.
	CodeChallengeMethodsSupported []string `json:"code_challenge_methods_supported"`
	// RegistrationEndpoint is the optional RFC 7591 dynamic-registration
	// endpoint, REPORTED but never invoked.
	RegistrationEndpoint string `json:"registration_endpoint,omitempty"`
	// Resource is the optional RFC 8707 resource identifier.
	Resource string `json:"resource,omitempty"`
	// SourceURL is the URL this metadata document was fetched from.
	SourceURL string `json:"source_url"`
}

type MCPBindingScopeCount struct {
	// BindingScope is the auth.BindingScope value ("user" / "agent").
	BindingScope string `json:"binding_scope"`
	// Count is the number of bindings at that scope.
	Count int32 `json:"count"`
}

type MCPBindingView struct {
	// PrincipalID is the bound principal — a user id (ScopeUser) or an
	// agent id (ScopeAgent).
	PrincipalID string `json:"principal_id"`
	// BindingScope is the auth.BindingScope value ("user" / "agent").
	BindingScope string `json:"binding_scope"`
	// Scopes is the configured OAuth scope list. Always non-nil.
	Scopes []string `json:"scopes"`
	// ExpiresAt is the access-token expiry, or zero when no token is
	// bound yet.
	ExpiresAt time.Time `json:"expires_at"`
	// LastUsedAt is the last-use instant, or zero when never used.
	LastUsedAt time.Time `json:"last_used_at"`
}

type MCPDiscoveryStepStatusView struct {
	// Step names the hop ("protected_resource" / "authorization_server").
	Step string `json:"step"`
	// Target is the URL the hop attempted.
	Target string `json:"target"`
	// OK reports whether the hop succeeded.
	OK bool `json:"ok"`
	// Reason is the stable machine-readable failure code (empty when OK).
	Reason string `json:"reason,omitempty"`
	// Detail is a human-readable message (never a credential).
	Detail string `json:"detail,omitempty"`
}

type MCPHealthBucket struct {
	// StartMs is the bucket start (Unix milliseconds).
	StartMs int64 `json:"start_ms"`
	// LatencyMs is the observed handshake latency for the bucket.
	LatencyMs int64 `json:"latency_ms"`
}

type MCPOAuthRequirementView struct {
	// ResourceMetadataURL is the RFC 9728 protected-resource-metadata URL the
	// discovery walked.
	ResourceMetadataURL string `json:"resource_metadata_url"`
	// AuthorizationServers is the verbatim RFC 8414 metadata for each
	// advertised authorization server that resolved. Always non-nil (may be
	// empty when the cross-origin AS hop was refused — see Status).
	AuthorizationServers []MCPAuthorizationServerView `json:"authorization_servers"`
	// DiscoveredAt is the wall-clock instant discovery ran.
	DiscoveredAt time.Time `json:"discovered_at"`
	// Source is "challenge" (a 401 WWW-Authenticate step-up) or "probe" (an
	// operator-triggered probe).
	Source string `json:"source"`
	// SourceURL is the resource-metadata URL discovery started from.
	SourceURL string `json:"source_url"`
	// Status is the typed per-hop outcome list — a partial chain reports the
	// hops it refused / failed here rather than surfacing silently empty.
	Status []MCPDiscoveryStepStatusView `json:"status"`
}

type MCPPromptArg struct {
	// Name is the argument name.
	Name string `json:"name"`
	// Description is the argument description.
	Description string `json:"description,omitempty"`
	// Required reports whether the argument is mandatory.
	Required bool `json:"required"`
}

type MCPPromptView struct {
	// Name is the prompt name.
	Name string `json:"name"`
	// Description is the prompt description.
	Description string `json:"description,omitempty"`
	// Arguments is the declared argument list. Always non-nil.
	Arguments []MCPPromptArg `json:"arguments"`
}

type MCPReconnect struct {
	// OccurredAt is the reconnect instant.
	OccurredAt time.Time `json:"occurred_at"`
	// Reason carries the reconnect cause.
	Reason string `json:"reason,omitempty"`
}

type MCPResourceArtifactRef struct {
	// ID is the content-addressed identifier (`{namespace}_{sha256[:12]}`).
	ID string `json:"id"`
	// MimeType is the IANA media type, when known.
	MimeType string `json:"mime_type,omitempty"`
	// SizeBytes is the length of the referenced bytes.
	SizeBytes int64 `json:"size_bytes,omitempty"`
	// Filename is metadata only (never used for path construction).
	Filename string `json:"filename,omitempty"`
	// SHA256 is the full hex digest of the referenced bytes.
	SHA256 string `json:"sha256,omitempty"`
}

type MCPResourceView struct {
	// URI is the resource URI.
	URI string `json:"uri"`
	// MimeType is the resource MIME type, or empty when the server
	// declared none.
	MimeType string `json:"mime_type,omitempty"`
	// SizeBytes is the declared resource size, or zero when unknown.
	SizeBytes int64 `json:"size_bytes,omitempty"`
	// Name is the resource short name.
	Name string `json:"name,omitempty"`
	// Title is the resource human-readable title.
	Title string `json:"title,omitempty"`
}

type MCPScopeShortfallView struct {
	// ToolName is the server-side tool name the shortfall was observed on
	// (empty when the observation was not tied to a specific tool call).
	ToolName string `json:"tool_name"`
	// DownstreamResource is the origin/host the challenge came from.
	DownstreamResource string `json:"downstream_resource"`
	// RequiredScopes is the parsed `scope` challenge parameter — the scopes
	// the downstream demands. Always non-nil in the wire JSON.
	RequiredScopes []string `json:"required_scopes"`
	// GrantedScopes is the binding's most-recently-granted scope set. Always
	// non-nil in the wire JSON (empty when unknown).
	GrantedScopes []string `json:"granted_scopes"`
	// WWWAuthenticate is the verbatim challenge header value.
	WWWAuthenticate string `json:"www_authenticate"`
	// Origin is the scheme://host[:port] the challenge was observed on.
	Origin string `json:"origin"`
	// ObservedAt is the wall-clock instant the shortfall was observed.
	ObservedAt time.Time `json:"observed_at"`
}

type MCPServerBindingsListRequest struct {
	// Identity is the mandatory caller identity scope.
	Identity IdentityScope `json:"identity"`
	// Name is the MCP server name. Required.
	Name string `json:"name"`
}

type MCPServerBindingsListResponse struct {
	// Bindings is the OAuth binding list. Always non-nil (may be empty).
	Bindings []MCPBindingView `json:"bindings"`
	// ProtocolVersion is the pinned Harbor Protocol version.
	ProtocolVersion string `json:"protocol_version"`
}

type MCPServerGetRequest struct {
	// Identity is the mandatory caller identity scope.
	Identity IdentityScope `json:"identity"`
	// Name is the MCP server name to inspect. Required.
	Name string `json:"name"`
}

type MCPServerGetResponse struct {
	// Server is the per-server row shape.
	Server MCPServerView `json:"server"`
	// DisplayModesAdvertised lists the MCP-Apps DisplayMode values the
	// server declares. Always non-nil in the wire JSON.
	DisplayModesAdvertised []string `json:"display_modes_advertised"`
	// ContentShapes lists the canonical content shapes the server's
	// tools return ("string" / "ImageRef" / ...). Always non-nil.
	ContentShapes []string `json:"content_shapes"`
	// ToolPolicy is the read-only ToolPolicy projection.
	ToolPolicy MCPToolPolicyView `json:"tool_policy"`
	// BindingsSummary is the per-scope binding count rollup. Always
	// non-nil in the wire JSON.
	BindingsSummary []MCPBindingScopeCount `json:"bindings_summary"`
	// ProtocolVersion is the pinned Harbor Protocol version.
	ProtocolVersion string `json:"protocol_version"`
}

type MCPServerHealthRequest struct {
	// Identity is the mandatory caller identity scope.
	Identity IdentityScope `json:"identity"`
	// Name is the MCP server name. Required.
	Name string `json:"name"`
}

type MCPServerHealthResponse struct {
	// HandshakeLatencyBuckets is the latency sparkline. Always non-nil.
	HandshakeLatencyBuckets []MCPHealthBucket `json:"handshake_latency_buckets"`
	// ReconnectHistory is the reconnect-history list. Always non-nil.
	ReconnectHistory []MCPReconnect `json:"reconnect_history"`
	// TransportErrorRate is the transport-error rate (errors / minute).
	TransportErrorRate float64 `json:"transport_error_rate"`
	// ProtocolVersion is the pinned Harbor Protocol version.
	ProtocolVersion string `json:"protocol_version"`
}

type MCPServerPolicyRequest struct {
	// Identity is the mandatory caller identity scope.
	Identity IdentityScope `json:"identity"`
	// Name is the MCP server name. Required.
	Name string `json:"name"`
}

type MCPServerPolicyResponse struct {
	// ToolPolicy is the read-only ToolPolicy projection.
	ToolPolicy MCPToolPolicyView `json:"tool_policy"`
	// ProtocolVersion is the pinned Harbor Protocol version.
	ProtocolVersion string `json:"protocol_version"`
}

type MCPServerProbeRequest struct {
	// Identity is the mandatory caller identity scope.
	Identity IdentityScope `json:"identity"`
	// Name is the MCP server name. Required.
	Name string `json:"name"`
}

type MCPServerProbeResponse struct {
	// OK reports whether the probe round-trip succeeded.
	OK bool `json:"ok"`
	// LatencyMs is the probe round-trip latency in milliseconds.
	LatencyMs int64 `json:"latency_ms"`
	// Error carries the probe failure message when OK is false.
	Error string `json:"error,omitempty"`
	// ProtocolVersion is the pinned Harbor Protocol version.
	ProtocolVersion string `json:"protocol_version"`
}

type MCPServerPromptsRequest struct {
	// Identity is the mandatory caller identity scope.
	Identity IdentityScope `json:"identity"`
	// Name is the MCP server name. Required.
	Name string `json:"name"`
}

type MCPServerPromptsResponse struct {
	// Prompts is the advertised prompt list. Always non-nil.
	Prompts []MCPPromptView `json:"prompts"`
	// ProtocolVersion is the pinned Harbor Protocol version.
	ProtocolVersion string `json:"protocol_version"`
}

type MCPServerRefreshBindingRequest struct {
	// Identity is the mandatory caller identity scope.
	Identity IdentityScope `json:"identity"`
	// Name is the MCP server name. Required.
	Name string `json:"name"`
	// PrincipalID is the binding principal to (re)connect. Optional —
	// empty drives the flow for the caller's own ScopeUser binding.
	PrincipalID string `json:"principal_id,omitempty"`
}

type MCPServerRefreshBindingResponse struct {
	// AuthorizeURL is the OAuth authorization endpoint URL the Console
	// navigates the popup to. NEVER a token.
	AuthorizeURL string `json:"authorize_url"`
	// State is the opaque flow-state the Console matches against the
	// subsequent tool.auth_completed event.
	State string `json:"state"`
	// ProtocolVersion is the pinned Harbor Protocol version.
	ProtocolVersion string `json:"protocol_version"`
}

type MCPServerRefreshDiscoveryRequest struct {
	// Identity is the mandatory caller identity scope.
	Identity IdentityScope `json:"identity"`
	// Name is the MCP server name. Required.
	Name string `json:"name"`
}

type MCPServerRefreshDiscoveryResponse struct {
	// DiscoveryID is an opaque id correlating this refresh with the
	// runtime logs.
	DiscoveryID string `json:"discovery_id"`
	// ToolCount / ResourceCount / PromptCount are the post-refresh
	// advertised counts.
	ToolCount     int32 `json:"tool_count"`
	ResourceCount int32 `json:"resource_count"`
	PromptCount   int32 `json:"prompt_count"`
	// ProtocolVersion is the pinned Harbor Protocol version.
	ProtocolVersion string `json:"protocol_version"`
}

type MCPServerResourcesRequest struct {
	// Identity is the mandatory caller identity scope.
	Identity IdentityScope `json:"identity"`
	// Name is the MCP server name. Required.
	Name string `json:"name"`
}

type MCPServerResourcesResponse struct {
	// Resources is the advertised resource list. Always non-nil.
	Resources []MCPResourceView `json:"resources"`
	// ProtocolVersion is the pinned Harbor Protocol version.
	ProtocolVersion string `json:"protocol_version"`
}

type MCPServerRevokeBindingRequest struct {
	// Identity is the mandatory caller identity scope.
	Identity IdentityScope `json:"identity"`
	// Name is the MCP server name. Required.
	Name string `json:"name"`
	// PrincipalID is the binding principal to revoke. Optional — empty
	// revokes the caller's own ScopeUser binding.
	PrincipalID string `json:"principal_id,omitempty"`
}

type MCPServerRevokeBindingResponse struct {
	// Revoked reports whether a binding was revoked.
	Revoked bool `json:"revoked"`
	// ProtocolVersion is the pinned Harbor Protocol version.
	ProtocolVersion string `json:"protocol_version"`
}

type MCPServerSetRawHTMLTrustRequest struct {
	// Identity is the mandatory caller identity scope.
	Identity IdentityScope `json:"identity"`
	// Name is the MCP server name. Required.
	Name string `json:"name"`
	// Trusted is the new per-server raw-HTML trust flag value.
	Trusted bool `json:"trusted"`
}

type MCPServerSetRawHTMLTrustResponse struct {
	// Name is the MCP server name the flag was set on.
	Name string `json:"name"`
	// Trusted is the persisted raw-HTML trust flag value.
	Trusted bool `json:"trusted"`
	// ProtocolVersion is the pinned Harbor Protocol version.
	ProtocolVersion string `json:"protocol_version"`
}

type MCPServerStateView string

type MCPServerView struct {
	// Name is the unique MCP server / source id.
	Name string `json:"name"`
	// Transport is the wire transport — "stdio", "http+sse",
	// "streamable-http", or "websocket".
	Transport string `json:"transport"`
	// URLOrCommand is the transport-prefixed endpoint URL (HTTP
	// transports) or the argv-form command string (stdio).
	URLOrCommand string `json:"url_or_command"`
	// State is the canonical state chip.
	State MCPServerStateView `json:"state"`
	// LastDiscoveryAt is the wall-clock instant of the last successful
	// discovery. Zero when discovery has never run.
	LastDiscoveryAt time.Time `json:"last_discovery_at"`
	// ToolCount is the number of tools the server advertises.
	ToolCount int32 `json:"tool_count"`
	// ResourceCount is the number of resources the server advertises.
	ResourceCount int32 `json:"resource_count"`
	// PromptCount is the number of prompts the server advertises.
	PromptCount int32 `json:"prompt_count"`
	// RecentLatencyMs is the most recent observed handshake / probe
	// latency in milliseconds.
	RecentLatencyMs int64 `json:"recent_latency_ms"`
	// ErrorRatePerMin is the transport-error rate over the recent
	// window (errors per minute).
	ErrorRatePerMin float64 `json:"error_rate_per_min"`
	// OAuthBindingCount is the number of OAuth bindings configured for
	// this server.
	OAuthBindingCount int32 `json:"oauth_binding_count"`
	// RawHTMLTrusted reports whether the per-server raw-HTML opt-in flag
	// is set. Default false (default-deny).
	RawHTMLTrusted bool `json:"raw_html_trusted"`
	// OAuthRequirement is the OAuth requirement the server ADVERTISED and
	// Harbor DISCOVERED on demand — the verbatim RFC 9728 → RFC 8414
	// metadata chain plus provenance. It is inert, server-supplied, UNVERIFIED
	// data: a proposal an operator confirms, never config Harbor follows —
	// Harbor never runs the OAuth flow, never holds a token, and never dials a
	// discovered endpoint. Present only on the DETAIL read (mcp.servers.get,
	// and after a probe triggers discovery); the list projection omits it so
	// the hot list row stays compact. Nil / omitted when no discovery has run.
	OAuthRequirement *MCPOAuthRequirementView `json:"oauth_requirement,omitempty"`
	// LastScopeShortfall is the last downstream insufficient-scope step-up
	// (a `403` + `WWW-Authenticate` marking `error="insufficient_scope"`)
	// observed on this connection — the required-vs-granted scope gap surfaced
	// as inert data. Present only on the DETAIL read (mcp.servers.get),
	// mirroring OAuthRequirement; the list projection omits it. Report-only:
	// Harbor never auto-escalates or re-consents on it. Nil / omitted when no
	// shortfall has been observed.
	LastScopeShortfall *MCPScopeShortfallView `json:"last_scope_shortfall,omitempty"`
}

type MCPServersListRequest struct {
	// Identity is the mandatory caller identity scope.
	Identity IdentityScope `json:"identity"`
	// State filters to servers in any of the given states. Empty = all.
	State []MCPServerStateView `json:"state,omitempty"`
	// Transport filters to servers on any of the given transports.
	Transport []string `json:"transport,omitempty"`
	// HasOAuth, when set, filters to servers with (true) / without
	// (false) at least one OAuth binding.
	HasOAuth *bool `json:"has_oauth,omitempty"`
	// HasRecentError, when set, filters to servers with (true) /
	// without (false) a recent transport error.
	HasRecentError *bool `json:"has_recent_error,omitempty"`
	// NamePrefix filters to servers whose name has the given prefix.
	NamePrefix string `json:"name_prefix,omitempty"`
	// PageToken is the opaque cursor from a prior response. Empty = the
	// first page.
	PageToken string `json:"page_token,omitempty"`
	// PageSize is the requested maximum row count. Zero = the surface
	// default; the surface clamps to a maximum.
	PageSize int32 `json:"page_size,omitempty"`
}

type MCPServersListResponse struct {
	// Servers is the page of server rows. Always non-nil in the wire
	// JSON (an empty list is `[]`, never `null`).
	Servers []MCPServerView `json:"servers"`
	// NextPageToken is the cursor for the next page, or empty when this
	// is the last page.
	NextPageToken string `json:"next_page_token,omitempty"`
	// ProtocolVersion is the pinned Harbor Protocol version.
	ProtocolVersion string `json:"protocol_version"`
}

type MCPToolPolicyView struct {
	// TimeoutMs is the per-invocation timeout in milliseconds.
	TimeoutMs int64 `json:"timeout_ms"`
	// MaxRetries is the retry cap.
	MaxRetries int32 `json:"max_retries"`
	// ConcurrencyCap is the per-server concurrent-invocation cap. Zero
	// means unbounded.
	ConcurrencyCap int32 `json:"concurrency_cap"`
}

type MemoryAggregates struct {
	// Total is the total record count across the filtered set.
	Total int64 `json:"total"`
	// IdentityRejected24h is the count of `memory.identity_rejected`
	// events observed in the last 24 hours.
	IdentityRejected24h int64 `json:"identity_rejected_24h"`
	// RecoveryDropped24h is the count of `memory.recovery_dropped`
	// events observed in the last 24 hours. The shipped wire
	// string is `memory.recovery_dropped` — page-memory.md §12 names a
	// mockup-refinement `memory.overflow_drop_oldest`; this phase uses
	// the shipped constant (see the phase plan "Findings I'm departing
	// from").
	RecoveryDropped24h int64 `json:"recovery_dropped_24h"`
}

type MemoryArtifactRef struct {
	// ID is the content-addressed identifier (`{namespace}_{sha256[:12]}`).
	ID string `json:"id"`
	// MimeType is the IANA media type, when known.
	MimeType string `json:"mime_type,omitempty"`
	// SizeBytes is the length of the referenced bytes.
	SizeBytes int64 `json:"size_bytes,omitempty"`
	// Filename is metadata only (never used for path construction).
	Filename string `json:"filename,omitempty"`
	// SHA256 is the full hex digest of the referenced bytes.
	SHA256 string `json:"sha256,omitempty"`
}

type MemoryDeleteRequest struct {
	// Identity is the request's identity scope. The triple is mandatory.
	Identity IdentityScope `json:"identity"`
	// Key is the memory turn key to evict — a value carried on a
	// `MemoryItem.Key` returned by `memory.list`.
	Key string `json:"key"`
}

type MemoryDeleteResponse struct {
	// Deleted is true when the keyed turn was found and evicted.
	Deleted bool `json:"deleted"`
	// RemainingTurns is the turn count remaining in the session record
	// after the eviction (the Console re-reads the list to refresh).
	RemainingTurns int `json:"remaining_turns"`
	// ProtocolVersion echoes the Protocol version the Runtime answered
	// under so a client can detect a version skew.
	ProtocolVersion string `json:"protocol_version"`
}

type MemoryDriverName string

type MemoryFilter struct {
	// TenantIDs narrows to a tenant set; empty = the caller's own
	// tenant. A foreign tenant OR len>1 requires auth.ScopeAdmin
	// (closed set).
	TenantIDs []string `json:"tenant_ids,omitempty"`
	// UserIDs narrows to a user set within the visible tenants.
	UserIDs []string `json:"user_ids,omitempty"`
	// SessionIDs narrows to a session set.
	SessionIDs []string `json:"session_ids,omitempty"`
	// AgentIDs narrows to records produced by a given agent set. NOT
	// an isolation filter (CLAUDE.md §6 clarifying note).
	AgentIDs []string `json:"agent_ids,omitempty"`
	// Scopes narrows to a subset of ["session", "user", "tenant"].
	// Each value must be a canonical MemoryScope.
	Scopes []string `json:"scopes,omitempty"`
	// Drivers narrows to a subset of ["inmem", "sqlite", "postgres"].
	// Each value must be a canonical MemoryDriverName.
	Drivers []string `json:"drivers,omitempty"`
	// Strategies narrows to a subset of the V1 MemoryStrategyName set.
	Strategies []string `json:"strategies,omitempty"`
	// ContentSearch is an optional substring matched against the
	// post-redaction record value text. The match is runtime-side
	// never a Console-side scan over an exported
	// snapshot.
	ContentSearch string `json:"content_search,omitempty"`
}

type MemoryGetRequest struct {
	// Identity is the request's identity scope. The triple is
	// mandatory; an incomplete triple fails closed with
	// CodeIdentityRequired (401).
	Identity IdentityScope `json:"identity"`
	// Key is the memory record key — the value carried on a
	// `MemoryItem.Key` returned by `memory.list`.
	Key string `json:"key"`
}

type MemoryGetResponse struct {
	// Detail is the full record detail.
	Detail MemoryItemDetail `json:"detail"`
	// ProtocolVersion echoes the Protocol version the Runtime answered
	// under so a client can detect a version skew.
	ProtocolVersion string `json:"protocol_version"`
}

type MemoryHealthAggregate struct {
	// Total is the total memory-record count for the caller's scope.
	Total int64 `json:"total"`
	// IdentityRejected24h is the count of `memory.identity_rejected`
	// events observed in the last 24 hours.
	IdentityRejected24h int64 `json:"identity_rejected_24h"`
	// RecoveryDropped24h is the count of `memory.recovery_dropped`
	// events observed in the last 24 hours.
	RecoveryDropped24h int64 `json:"recovery_dropped_24h"`
	// DriverByScope maps each memory scope to the persistence driver
	// backing it — e.g. {"session":"inmem", "tenant":"postgres"}. The
	// driver-comparison rollup the Memory page renders.
	DriverByScope map[string]string `json:"driver_by_scope"`
}

type MemoryHealthRequest struct {
	// Identity is the request's identity scope. The triple is
	// mandatory; an incomplete triple fails closed with
	// CodeIdentityRequired (401).
	Identity IdentityScope `json:"identity"`
}

type MemoryHealthResponse struct {
	// Aggregate carries the aggregate health counters.
	Aggregate MemoryHealthAggregate `json:"aggregate"`
	// ProtocolVersion echoes the Protocol version the Runtime answered
	// under so a client can detect a version skew.
	ProtocolVersion string `json:"protocol_version"`
}

type MemoryItem struct {
	// Key is the memory record key — a deterministic per-record
	// identifier the Console passes back to `memory.get`. A client
	// never constructs or parses it.
	Key string `json:"key"`
	// Strategy is the memory strategy this record was produced under —
	// one of the MemoryStrategyName values.
	Strategy string `json:"strategy"`
	// Scope is the record's scope — "session" | "user" | "tenant".
	Scope string `json:"scope"`
	// Identity is the (tenant, user, session [, run]) the record lives
	// under. Flat strings — never a re-export of the runtime identity
	// quadruple.
	Identity IdentityScope `json:"identity"`
	// AgentID is the registration identity of the agent that produced
	// the record, when known. NOT an isolation principal (CLAUDE.md §6
	// clarifying note) — surfaced for the Owner column only.
	AgentID string `json:"agent_id,omitempty"`
	// CreatedAt is the wall-clock time the record was first written.
	CreatedAt time.Time `json:"created_at"`
	// LastUpdatedAt is the wall-clock time the record was last touched.
	LastUpdatedAt time.Time `json:"last_updated_at"`
	// ExpiresAt is the record's TTL expiry; the zero value (omitted)
	// means the record has no TTL.
	ExpiresAt time.Time `json:"expires_at,omitempty"`
	// SizeBytes is the byte length of the record's post-redaction
	// value. A count only — the bytes themselves are never inlined on
	// this row shape.
	SizeBytes int64 `json:"size_bytes"`
	// HeavyContent is true when SizeBytes meets or exceeds the
	// heavy-content threshold; the Console renders a heavy-content icon
	// and `memory.get` returns a `MemoryArtifactRef` for the value.
	HeavyContent bool `json:"heavy_content,omitempty"`
	// Driver is the persistence driver backing this record —
	// "inmem" | "sqlite" | "postgres".
	Driver string `json:"driver"`
}

type MemoryItemDetail struct {
	// Item is the row-shaped projection of the record (the same shape
	// `memory.list` returns).
	Item MemoryItem `json:"item"`
	// Value is the post-redaction record value, populated ONLY when
	// SizeBytes is below the heavy-content threshold.
	Value []byte `json:"value,omitempty"`
	// ValueArtifact is populated when SizeBytes meets or exceeds the
	// heavy-content threshold. The Console fetches the bytes
	// via `artifacts.get` against this stub. When ValueArtifact is set,
	// Value is nil — and vice-versa.
	ValueArtifact *MemoryArtifactRef `json:"value_artifact,omitempty"`
	// Metadata carries the per-record metadata.
	Metadata MemoryMetadata `json:"metadata"`
}

type MemoryListRequest struct {
	// Identity is the request's identity scope. The triple is
	// mandatory; an incomplete triple fails the request closed at the
	// Protocol edge with CodeIdentityRequired (401).
	Identity IdentityScope `json:"identity"`
	// Filter narrows the listed records. Empty filter = the caller's
	// own identity scope, every record.
	Filter MemoryFilter `json:"filter,omitempty"`
	// Page is the 1-based page number; defaults to 1 when zero. A
	// negative Page is rejected with CodeInvalidRequest (400).
	Page int `json:"page,omitempty"`
	// PageSize is the per-page row count. Defaults to
	// DefaultMemoryListPageSize (50) when zero; values above
	// MaxMemoryListPageSize (200) — or negative — are rejected with
	// CodeInvalidRequest (400). Never silently clamped.
	PageSize int `json:"page_size,omitempty"`
}

type MemoryListResponse struct {
	// Items is the page of memory records, ordered LastUpdatedAt
	// descending (newest first) for a deterministic table.
	Items []MemoryItem `json:"items"`
	// Page is the 1-based page number this response covers.
	Page int `json:"page"`
	// PageSize is the per-page row count applied.
	PageSize int `json:"page_size"`
	// PageCount is the total number of pages over the filtered set.
	PageCount int `json:"page_count"`
	// TotalRows is the total filtered row count across all pages.
	TotalRows int `json:"total_rows"`
	// Aggregates carries the page-level counters.
	Aggregates MemoryAggregates `json:"aggregates"`
	// ProtocolVersion echoes the Protocol version the Runtime answered
	// under so a client can detect a version skew.
	ProtocolVersion string `json:"protocol_version"`
}

type MemoryMetadata struct {
	// TTL is the record's configured time-to-live. The zero value
	// means the record has no TTL.
	TTL time.Duration `json:"ttl,omitempty"`
	// StrategyConfig is the bounded, strategy-named knob map surfaced
	// for the right-rail detail (e.g. budget tokens for `truncation`).
	StrategyConfig map[string]string `json:"strategy_config,omitempty"`
	// RelatedEventIDs are the recent event IDs touching this record's
	// key — for the right-rail "Inspect related events" deep-link.
	RelatedEventIDs []string `json:"related_event_ids,omitempty"`
}

type MemoryPutRequest struct {
	// Identity is the request's identity scope. The triple is mandatory.
	Identity IdentityScope `json:"identity"`
	// Turn is the conversation turn to append.
	Turn MemoryTurnInput `json:"turn"`
}

type MemoryPutResponse struct {
	// Key is the deterministic key of the appended turn — the value a
	// subsequent `memory.get` resolves.
	Key string `json:"key"`
	// ProtocolVersion echoes the Protocol version the Runtime answered
	// under so a client can detect a version skew.
	ProtocolVersion string `json:"protocol_version"`
}

type MemoryScope string

type MemoryStrategyName string

type MemoryStrategyTrace struct {
	// Strategy is the configured memory strategy — one of the
	// MemoryStrategyName values.
	Strategy string `json:"strategy"`
	// Summary is the rolling-summary text the strategy injects into the
	// planner's LLM call — the compaction OUTPUT. Empty under `none` /
	// `truncation` (which keep no rolling summary) or before any
	// compaction has occurred.
	Summary string `json:"summary"`
	// RecentTurnCount is the number of conversation turns the strategy
	// currently keeps verbatim (NOT folded into the summary).
	RecentTurnCount int `json:"recent_turn_count"`
	// EstimatedTokens is the strategy's current estimate of the tokens
	// `GetLLMContext` would inject — the planner compares this against its
	// context-window budget.
	EstimatedTokens int `json:"estimated_tokens"`
	// Health is the memory FSM health state for this identity —
	// "healthy" | "degraded" | "recovering".
	Health string `json:"health"`
}

type MemoryStrategyTraceRequest struct {
	// Identity is the request's identity scope. The triple is mandatory;
	// an incomplete triple fails closed with CodeIdentityRequired (401).
	Identity IdentityScope `json:"identity"`
}

type MemoryStrategyTraceResponse struct {
	// Trace is the live strategy-compaction projection.
	Trace MemoryStrategyTrace `json:"trace"`
	// ProtocolVersion echoes the Protocol version the Runtime answered
	// under so a client can detect a version skew.
	ProtocolVersion string `json:"protocol_version"`
}

type MemoryTurnInput struct {
	// UserMessage is the turn's user message text.
	UserMessage string `json:"user_text"`
	// AssistantResponse is the turn's assistant response text.
	AssistantResponse string `json:"assistant_text"`
}

type MetricsSnapshot struct {
	// Counters is the flat counter-metric slice.
	Counters []NamedCounter `json:"counters"`
	// Histograms is the flat histogram-metric slice.
	Histograms []NamedHistogram `json:"histograms"`
	// Gauges is the flat gauge-metric slice.
	Gauges []NamedGauge `json:"gauges"`
	// SnapshotAt is the unix-millis timestamp the metrics were read.
	SnapshotAt int64 `json:"snapshot_at"`
}

type NamedCounter struct {
	// Name is the metric name.
	Name string `json:"name"`
	// Value is the counter's current value.
	Value float64 `json:"value"`
	// Labels carries the metric's low-cardinality label set. A
	// high-cardinality label (run_id / trace_id / span_id) never appears
	// here — the cardinality firewall gates it on the SDK side,
	// and MetricsSnapshot.HasHighCardinalityLabel is the wire-boundary
	// cardinalitylint guard (exercised by the posture type tests).
	Labels map[string]string `json:"labels,omitempty"`
}

type NamedGauge struct {
	// Name is the metric name.
	Name string `json:"name"`
	// Value is the gauge's current value.
	Value float64 `json:"value"`
	// Labels carries the metric's low-cardinality label set.
	Labels map[string]string `json:"labels,omitempty"`
}

type NamedHistogram struct {
	// Name is the metric name.
	Name string `json:"name"`
	// Count is the total observation count.
	Count uint64 `json:"count"`
	// Sum is the sum of all observed values.
	Sum float64 `json:"sum"`
	// Buckets is the cumulative per-bucket count slice.
	Buckets []HistogramBucket `json:"buckets,omitempty"`
	// Labels carries the metric's low-cardinality label set.
	Labels map[string]string `json:"labels,omitempty"`
}

type PauseArtifactRef struct {
	// ID is the content-addressed identifier (`{namespace}_{sha256[:12]}`).
	ID string `json:"id"`
	// MimeType is the IANA media type, when known.
	MimeType string `json:"mime_type,omitempty"`
	// SizeBytes is the length of the referenced bytes.
	SizeBytes int64 `json:"size_bytes,omitempty"`
	// Filename is metadata only (never used for path construction).
	Filename string `json:"filename,omitempty"`
	// SHA256 is the full hex digest of the referenced bytes.
	SHA256 string `json:"sha256,omitempty"`
}

type PauseFilter struct {
	// Status filters by lifecycle state; empty defaults to ["paused"].
	// Each value must be a canonical PauseSnapshotState.
	Status []string `json:"status,omitempty"`
	// TenantIDs narrows to a tenant set; empty defaults to the
	// caller's own tenant. A foreign tenant OR len>1 requires admin.
	TenantIDs []string `json:"tenant_ids,omitempty"`
	// UserIDs narrows to a user set within the visible tenants.
	UserIDs []string `json:"user_ids,omitempty"`
	// SessionIDs narrows to a session set.
	SessionIDs []string `json:"session_ids,omitempty"`
	// RunIDs narrows to a run set.
	RunIDs []string `json:"run_ids,omitempty"`
	// Reasons narrows to one or more canonical pause reasons.
	Reasons []string `json:"reasons,omitempty"`
	// Since is an optional lower bound on PausedAt (inclusive).
	Since time.Time `json:"since,omitempty"`
	// Until is an optional upper bound on PausedAt (inclusive).
	Until time.Time `json:"until,omitempty"`
}

type PauseListRequest struct {
	// Identity is the request's identity scope. The triple is
	// mandatory; an incomplete triple fails the request closed at the
	// Protocol edge with CodeIdentityRequired (401).
	Identity IdentityScope `json:"identity"`
	// Filter narrows the snapshot. Empty filter = caller's own
	// identity scope, status=paused.
	Filter PauseFilter `json:"filter,omitempty"`
	// Page is the 1-based page number; defaults to 1 when zero. A
	// negative Page is rejected with CodeInvalidRequest (400).
	Page int `json:"page,omitempty"`
	// PageSize is the per-page row count. Defaults to
	// DefaultPauseListPageSize (50) when zero; values above
	// MaxPauseListPageSize (200) — or negative — are rejected with
	// CodeInvalidRequest (400). Never silently clamped.
	PageSize int `json:"page_size,omitempty"`
}

type PauseListResponse struct {
	// Snapshots is the page of pause records, ordered PausedAt
	// descending (newest first) for a deterministic intervention
	// queue.
	Snapshots []PauseSnapshot `json:"snapshots"`
	// Page is the 1-based page number this response covers.
	Page int `json:"page"`
	// PageSize is the per-page row count applied.
	PageSize int `json:"page_size"`
	// PageCount is the total number of pages over the filtered set.
	PageCount int `json:"page_count"`
	// TotalRows is the total filtered row count across all pages.
	TotalRows int `json:"total_rows"`
	// Truncated is true when a status=resumed filter aged out beyond
	// the in-memory registry's retention. The Coordinator's
	// resumed-records retention is bounded by the destructive-on-resume
	// contract (coordinator.go) — a resumed Token is
	// queryable only until the Coordinator clears it. Operators
	// inspecting historical resume activity should use
	// `events.subscribe` on the `pause.resumed` topic instead.
	Truncated bool `json:"truncated,omitempty"`
}

type PauseSnapshot struct {
	// Token is the opaque runtime-issued pause Token (RFC §6.3). A
	// client never constructs or parses it; it is the handle the
	// `resume` / `approve` / `reject` methods take.
	Token string `json:"token"`
	// Reason is one of the four canonical pause reasons (RFC §6.3).
	Reason string `json:"reason"`
	// State is the lifecycle state — "paused" or "resumed".
	State PauseSnapshotState `json:"state"`
	// Identity is the (tenant, user, session [, run]) the pause was
	// recorded under. Flat strings — never a re-export of the runtime
	// identity quadruple.
	Identity IdentityScope `json:"identity"`
	// PausedAt is the wall-clock time the pause was recorded.
	PausedAt time.Time `json:"paused_at"`
	// ResumedAt is the wall-clock time Resume was called; the zero
	// value (omitted) unless State == "resumed".
	ResumedAt time.Time `json:"resumed_at,omitempty"`
	// Payload is the sanitised pause payload INLINE when its serialised
	// size is below the heavy-content threshold. Otherwise the runtime
	// routes it through the ArtifactStore and ships PayloadRef instead
	// (context-window safety net applied to Protocol snapshots).
	// Exactly one of Payload / PayloadRef is populated for a pause
	// carrying a payload; both are empty for a payload-free pause.
	Payload map[string]any `json:"payload,omitempty"`
	// PayloadRef is populated when the pause record's Payload exceeded
	// the heavy-content threshold. The Console fetches the
	// bytes via `artifacts.get` / `artifacts.get_ref` when it wants
	// them. When PayloadRef is set, Payload is nil.
	PayloadRef *PauseArtifactRef `json:"payload_ref,omitempty"`
}

type PauseSnapshotState string

type RateLimitView struct {
	// Capacity is the bucket ceiling (max reservable tokens). 0 disables
	// the rate limit even if the refill knobs are set.
	Capacity int `json:"capacity"`
	// RefillTokens are added to the bucket every refill tick.
	RefillTokens int `json:"refill_tokens"`
	// RefillIntervalMS is the refill tick duration in milliseconds. The
	// Go side holds a time.Duration; this is its millisecond projection.
	RefillIntervalMS int64 `json:"refill_interval_ms"`
}

type ReadMCPResourceRequest struct {
	// Identity is the (tenant, user, session) scope the read runs under.
	// Mandatory — an incomplete triple fails closed.
	Identity IdentityScope `json:"identity"`
	// ServerID is the MCP server (source id) hosting the resource.
	ServerID string `json:"server_id"`
	// ResourceURI is the resource to fetch — the `ui://`-scheme URI of
	// an MCP App's UI document for app fetches.
	ResourceURI string `json:"resource_uri"`
}

type ReadMCPResourceResponse struct {
	// ResourceURI echoes the fetched resource URI.
	ResourceURI string `json:"resource_uri"`
	// MIMEType is the resource's declared media type.
	MIMEType string `json:"mime_type,omitempty"`
	// Content is the inline resource bytes, populated ONLY when the
	// content is below the heavy-content threshold. Empty when
	// ArtifactRef is set.
	Content string `json:"content,omitempty"`
	// ArtifactRef is the by-reference stub, populated when the content
	// meets or exceeds the heavy-content threshold. Nil when Content is
	// set.
	ArtifactRef *MCPResourceArtifactRef `json:"artifact_ref,omitempty"`
	// ProtocolVersion echoes the Protocol version the Runtime answered
	// under so a client can detect a version skew.
	ProtocolVersion string `json:"protocol_version"`
}

type RetentionHorizon struct {
	// Surface names the durable surface this horizon covers — one of
	// "events", "tasks", "sessions". The "events" entry also covers the
	// conversation-history read, whose substrate IS the event log.
	Surface string `json:"surface"`
	// Scope names the identity scope this horizon was measured AT — one
	// of "runtime" (identity-free, the whole retained set), "tenant" (the
	// caller's tenant), or "session" (the caller's full triple). It makes
	// the ABSENCE of a value representable: a consumer reading a
	// no-timestamp entry distinguishes `scope:"runtime"` + no-timestamp
	// ("the runtime retains nothing — a trustworthy empty") from
	// `scope:"session"` / `scope:"tenant"` + no-timestamp ("nothing at
	// YOUR scope — the runtime-wide truth is not observable here") and so
	// degrades honestly (marks a fleet window's completeness unverifiable)
	// rather than silently trusting a shorter or absent horizon as
	// runtime-wide truth. The `events` horizon is always "runtime"; the
	// `tasks` / `sessions` horizons are "session" / "tenant" for an
	// ordinary caller and widen to "runtime" for a verified admin /
	// console:fleet fleet-observe caller. Omitted (empty) for an
	// older/headless wiring that does not stamp a scope.
	Scope string `json:"scope,omitempty"`
	// OldestRetainedAt is the RFC-3339 wall-clock time of the oldest row
	// the surface currently retains AT `Scope`. It is a pointer so a nil
	// value is genuinely OMITTED from the JSON (a zero `time.Time` value
	// would marshal as a real-looking "0001-01-01T00:00:00Z" and defeat
	// the absence-representable contract). Nil/absent when the surface
	// holds no rows at that scope — never a fabricated value. Read WITH
	// `Scope`: an omitted timestamp is a true empty only when `Scope` is
	// "runtime"; at "session" / "tenant" it means the runtime-wide horizon
	// is simply not observable at the caller's scope.
	OldestRetainedAt *time.Time `json:"oldest_retained_at,omitempty"`
}

type RunOverrides struct {
	// SessionID is the session the override applies to. Mandatory — an
	// empty SessionID fails the request closed at the Protocol edge
	// (identity is mandatory, CLAUDE.md §6 rule 9). The tenant and user
	// components of the isolation triple are inferred from the verified
	// JWT; only the session is named on the wire.
	SessionID string `json:"session_id"`
	// ReasoningEffort, when non-nil, overrides the LLM reasoning-effort
	// hint for the next message. Values follow the bound LLM provider's
	// taxonomy (e.g. `low` / `medium` / `high`); the runtime validates
	// the string against the provider's accepted set and rejects an
	// unknown value with CodeInvalidRequest.
	ReasoningEffort *string `json:"reasoning_effort,omitempty"`
	// Temperature, when non-nil, overrides the sampling temperature for
	// the next message. The runtime rejects a value outside the closed
	// range [0, 2] with CodeInvalidRequest.
	Temperature *float64 `json:"temperature,omitempty"`
	// MaxTokens, when non-nil, overrides the per-message MaxTokens
	// governance ceiling for the next message. The runtime rejects a
	// non-positive value with CodeInvalidRequest.
	MaxTokens *int `json:"max_tokens,omitempty"`
	// SystemPromptOverride, when non-nil, replaces the agent's system
	// prompt for the next message only. An empty string is a valid
	// override (it clears the system prompt for that one message);
	// nil means "leave the agent's configured system prompt in place".
	SystemPromptOverride *string `json:"system_prompt_override,omitempty"`
	// Model, when non-nil, overrides the model the next message's run
	// requests. The runtime rejects a model with no configured
	// `ModelProfile` with CodeInvalidRequest (fail loud at set time). The
	// session-level model swap — it wins over the tenant default and the
	// config default for that one message (session › tenant › config).
	Model *string `json:"model,omitempty"`
}

type RunSetOverridesRequest struct {
	// Identity is the request's identity scope. The triple is mandatory;
	// the runtime cross-checks Identity.Session against
	// Overrides.SessionID and rejects a mismatch with CodeScopeMismatch
	// (a caller cannot set an override for a session outside its own
	// verified scope).
	Identity IdentityScope `json:"identity"`
	// Overrides is the next-message override payload.
	Overrides RunOverrides `json:"overrides"`
}

type RunSetOverridesResponse struct {
	// AppliedAt is the runtime timestamp at which the override was
	// recorded. It is the moment the override entered the session's
	// pending-override slot — not the moment a subsequent message
	// consumed it.
	AppliedAt time.Time `json:"applied_at"`
	// ProtocolVersion echoes the Protocol version the Runtime answered
	// with, so a Console can assert wire compatibility.
	ProtocolVersion string `json:"protocol_version"`
}

type RuntimeCounters struct {
	// EventsPerSecond is the recent bus-emit rate.
	EventsPerSecond float64 `json:"events_per_second"`
	// TasksRunning is the count of foreground/background tasks
	// currently in a running state.
	TasksRunning int64 `json:"tasks_running"`
	// BackgroundJobsActive is the count of background jobs in flight.
	BackgroundJobsActive int64 `json:"background_jobs_active"`
	// MCPConnectionsHealthy is the count of healthy MCP southbound
	// connections.
	MCPConnectionsHealthy int64 `json:"mcp_connections_healthy"`
	// SessionsActive is the count of currently-active sessions.
	SessionsActive int64 `json:"sessions_active"`
	// SnapshotAt is the unix-millis timestamp the counters were read.
	SnapshotAt int64 `json:"snapshot_at"`
}

type RuntimeDrivers struct {
	// Subsystems is the per-subsystem driver slice.
	Subsystems []SubsystemDriver `json:"subsystems"`
}

type RuntimeHealth struct {
	// Subsystems is the per-subsystem readiness slice — one entry per
	// subsystem the runtime knows about.
	Subsystems []SubsystemHealth `json:"subsystems"`
	// Retention is the observed retention horizon per durable surface —
	// the oldest-retained timestamp for "events", "tasks", and
	// "sessions". Additive: an older client that does not read it is
	// unaffected. A surface with no rows yet, or a runtime that wired no
	// retention seam for it, simply omits its entry (the whole slice is
	// omitted when empty). Values are OBSERVED, never configured claims —
	// see RetentionHorizon.
	Retention []RetentionHorizon `json:"retention,omitempty"`
}

type RuntimeInfo struct {
	// InstanceID is a stable per-deployment identifier minted at boot.
	// A Console managing several Runtimes keys each attachment by it.
	InstanceID string `json:"instance_id"`
	// DisplayName is the operator-configured friendly name for this
	// Runtime. Empty when the operator configured none — never the
	// host's machine name without explicit operator config.
	DisplayName string `json:"display_name,omitempty"`
	// BuildVersion is the Harbor build version string (e.g. a release
	// tag or a `v0.0.0-dev` dev marker).
	BuildVersion string `json:"build_version"`
	// BuildCommit is the VCS revision the binary was built from, or
	// "unknown" when the build carried no VCS stamp.
	BuildCommit string `json:"build_commit"`
	// BuildDate is the build timestamp (RFC 3339), or empty when the
	// build carried no date stamp.
	BuildDate string `json:"build_date,omitempty"`
	// BuildGoVersion is the Go toolchain version the binary was built
	// with.
	BuildGoVersion string `json:"build_go_version"`
	// ProtocolVersion is the pinned Harbor Protocol version the Runtime
	// speaks (the ProtocolVersion constant). A client parses it and
	// checks Version.Compatible against its own.
	ProtocolVersion string `json:"protocol_version"`
	// Capabilities is the set of Protocol surfaces the Runtime
	// advertises as live — the same set CurrentHandshake() carries.
	Capabilities []Capability `json:"capabilities"`
	// UptimeSeconds is the number of whole seconds since the Runtime
	// process started.
	UptimeSeconds int64 `json:"uptime_seconds"`
	// MCPAppDisplayModes is the set of MCP App (`io.modelcontextprotocol/ui`)
	// display modes this host can render, declared by the deployment's
	// `tools.mcp_app_host.display_modes` config. A Protocol client (the
	// Console) reads it to seed the `ui/initialize` host-context
	// `availableDisplayModes` it advertises to a rendered app — display modes
	// are a host-context value, not an MCP capability field. Empty when the
	// deployment declared none.
	MCPAppDisplayModes []string `json:"mcp_app_display_modes,omitempty"`
	// WireSurfaceDigest is the opaque, stable name-level digest of the
	// runtime's canonical Protocol wire surface — a `sha256:…` fingerprint
	// over the Protocol version, method names, error codes, capability
	// strings, and wire-type names. A client compares it against the digest
	// it was built against and surfaces a loud drift signal on a mismatch,
	// so coarse wire drift is detectable at connect-time without exposing
	// field shapes over the wire. It covers the SHAPE OF NAMES, not field
	// shapes and not event-type names.
	WireSurfaceDigest string `json:"wire_surface_digest"`
}