types

type Agent struct {
	// ID is the agent_id — the stable registration identity (D-059).
	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 (D-059).
	Incarnation int64 `json:"incarnation"`
	// VersionHash is the SHA-256 over canonical JSON of AgentConfig
	// (D-068). 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"`
}

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 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"`
}

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 (Phase 24).
	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
	// (Phase 41) rather than imported (Phase 38).
	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
	// D-083): "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 (D-120 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 D-079.
	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 Phase 52
	// 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 — Phase 53's 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. Round-5 walkthrough fix — pre-fix the request 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"`
}

type EventAggregateResponse struct {
	// Buckets is the per-bucket count series, oldest first. Each
	// bucket's [Start, End) span is exactly `Request.Bucket` wide; the
	// last bucket's End equals the request's effective Now.
	Buckets []EventBucket `json:"buckets"`
	// ProtocolVersion echoes the Protocol version the Runtime answered
	// under so a client can detect a version skew (mirrors the
	// Phase 54 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 Phase 54 task-control method
	// name start — the Phase 58 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"`
}

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 D-079.
	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 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 (D-063).
	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 (D-023). 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 (D-026). 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 (D-079).
	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"`
}

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 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 D-081
	// 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 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 Phase 61 Protocol auth, exactly
	// as `events.Filter.Admin` is; the ControlSurface enforces the
	// per-method scope via the Phase 52 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 Phase 61 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. Brief 11 §PG-5, Phase 72b, D-107.
	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. Brief 11 §PG-5, Phase 72b, D-107.
	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. Brief 11 §PG-5, Phase
	// 72b, D-107.
	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
	// (D-089). 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 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 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 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 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 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 (D-062). 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 — brief 11 §8).
	RawHTMLTrusted bool `json:"raw_html_trusted"`
}

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"`
	// ExpiringIn1h is the count of records whose ExpiresAt falls
	// within (now, now+1h].
	ExpiringIn1h int64 `json:"expiring_in_1h"`
	// IdentityRejected24h is the count of `memory.identity_rejected`
	// events (D-033) observed in the last 24 hours.
	IdentityRejected24h int64 `json:"identity_rejected_24h"`
	// RecoveryDropped24h is the count of `memory.recovery_dropped`
	// events (D-035) 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
	// (D-079 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"`
	// HasTTLExpiring, when true, narrows to records whose ExpiresAt
	// falls within (now, now+1h].
	HasTTLExpiring bool `json:"has_ttl_expiring,omitempty"`
	// ContentSearch is an optional substring matched against the
	// post-redaction record value text. The match is runtime-side
	// (brief 11 §CC-4) — 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"`
	// ExpiringIn1h is the count of records whose TTL expires within
	// the next hour.
	ExpiringIn1h int64 `json:"expiring_in_1h"`
	// IdentityRejected24h is the count of `memory.identity_rejected`
	// events (D-033) observed in the last 24 hours.
	IdentityRejected24h int64 `json:"identity_rejected_24h"`
	// RecoveryDropped24h is the count of `memory.recovery_dropped`
	// events (D-035) 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 D-026
	// 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 (D-026).
	Value []byte `json:"value,omitempty"`
	// ValueArtifact is populated when SizeBytes meets or exceeds the
	// heavy-content threshold (D-026). 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 Phase 56 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 (Phase 50 / 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
	// Phase 54 `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
	// (D-026 — 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 (D-026). 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 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"`
}

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"`
}

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"`
}

type RuntimeInfoRequest struct {
	// Identity is the caller's identity scope. The PostureSurface
	// validates the triple and gates cross-tenant reads on the admin
	// scope claim.
	Identity IdentityScope `json:"identity"`
}

type SearchArtifactRef 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 SearchFacet struct {
	// Key is the facet dimension name (e.g. `tasks.status`).
	Key string `json:"key"`
	// Value is the facet's selected value (e.g. `running`).
	Value string `json:"value"`
}

type SearchFilter struct {
	// TenantIDs narrows the search to these tenants; empty defaults to
	// the caller's authenticated tenant. A value outside the caller's
	// own tenant requires the `auth.ScopeAdmin` claim.
	TenantIDs []string `json:"tenant_ids,omitempty"`
	// UserIDs narrows the search to these users; empty defaults to the
	// caller's authenticated user.
	UserIDs []string `json:"user_ids,omitempty"`
	// SessionIDs narrows the search to these sessions; empty defaults to
	// the caller's authenticated session.
	SessionIDs []string `json:"session_ids,omitempty"`
	// Since is the inclusive lower bound of the result time-window; the
	// zero value imposes no lower bound.
	Since time.Time `json:"since,omitempty"`
	// Until is the inclusive upper bound of the result time-window; the
	// zero value imposes no upper bound.
	Until time.Time `json:"until,omitempty"`
}

type SearchIndex string

type SearchRequest struct {
	// Query is the free-text query — substring / prefix match against
	// the searched fields per index. Empty Query is permitted (lists
	// everything in scope subject to filters).
	Query string `json:"query,omitempty"`
	// Indexes selects which runtime-side indexes `search.query` should
	// fan out to. Empty means "all four." Ignored by the four per-index
	// methods. Unknown index values are rejected with
	// `CodeInvalidRequest`.
	Indexes []SearchIndex `json:"indexes,omitempty"`
	// Filter narrows results. Identity defaulting + cross-tenant gating
	// happens in the search handler — the wire surface accepts every
	// caller's filter and rejects elevated requests loudly.
	Filter SearchFilter `json:"filter,omitempty"`
	// Facets are optional per-index dimension selectors. The runtime
	// applies whichever facets are recognised for the index being
	// searched and silently ignores the rest.
	Facets []SearchFacet `json:"facets,omitempty"`
	// Page is the 1-based page number; defaults to 1 when zero.
	Page int `json:"page,omitempty"`
	// PageSize is the per-page row count. Defaults to
	// `DefaultSearchPageSize` (20) when zero; values above
	// `MaxSearchPageSize` (200) are rejected with `CodeInvalidRequest`.
	PageSize int `json:"page_size,omitempty"`
}

type SearchResponse struct {
	// Rows is the page slice — at most `PageSize` rows. Empty when
	// the filter matched nothing.
	Rows []SearchResultRow `json:"rows"`
	// Page echoes the (defaulted) request page.
	Page int `json:"page"`
	// PageSize echoes the (defaulted) per-page size.
	PageSize int `json:"page_size"`
	// PageCount is the total page count given TotalCount + PageSize.
	PageCount int `json:"page_count"`
	// TotalCount is the total matching row count BEFORE pagination.
	TotalCount int64 `json:"total_count"`
	// HasMore is a convenience flag — true when Page < PageCount.
	HasMore bool `json:"has_more"`
	// ProtocolVersion echoes the Protocol version the Runtime answered
	// under so a client can detect a version skew.
	ProtocolVersion string `json:"protocol_version"`
}

type SearchResultRow struct {
	// Index identifies which subsystem produced the row. Required.
	Index SearchIndex `json:"index"`
	// ID is the entity identifier (session ID / task ID / event ID
	// (composed `<session>:<sequence>`) / artifact ID).
	ID string `json:"id"`
	// TenantID + UserID + SessionID + RunID flatten the runtime's
	// identity quadruple so a Protocol client never round-trips a
	// runtime Go struct. RunID is empty for session-scoped entities.
	TenantID  string `json:"tenant_id"`
	UserID    string `json:"user_id"`
	SessionID string `json:"session_id"`
	RunID     string `json:"run_id,omitempty"`
	// OccurredAt is the row's anchor timestamp — for sessions, the
	// open / last-seen / close time; for tasks, UpdatedAt; for events,
	// OccurredAt; for artifacts, the put time (mirrored by the
	// driver's UpdatedAt when known).
	OccurredAt time.Time `json:"occurred_at,omitempty"`
	// Preview is the redacted short summary (≤ heavy-content
	// threshold). Empty when Ref is populated.
	Preview string `json:"preview,omitempty"`
	// Ref is populated when the underlying entity's preview would
	// exceed the heavy-content threshold (D-026). The Console fetches
	// the bytes via `artifacts.get` / `artifacts.get_ref` when it
	// wants them.
	Ref *SearchArtifactRef `json:"ref,omitempty"`
	// Facets carries per-index dimension values relevant to the row
	// (e.g. `{"status":"running"}` for tasks). The set of populated
	// keys per index is documented per Searcher implementation.
	Facets map[string]string `json:"facets,omitempty"`
}

type SessionFilter struct {
	// Statuses restricts to sessions whose Status is in this set.
	Statuses []SessionStatus `json:"statuses,omitempty"`
	// AgentIDs restricts to sessions whose AgentID is in this set.
	AgentIDs []string `json:"agent_ids,omitempty"`
	// UserIDs restricts to sessions whose UserID is in this set.
	UserIDs []string `json:"user_ids,omitempty"`
	// TenantIDs restricts to sessions whose TenantID is in this set.
	// A TenantIDs entry naming a tenant other than the caller's
	// verified tenant requires the `auth.ScopeAdmin` claim (D-079).
	TenantIDs []string `json:"tenant_ids,omitempty"`
	// StartedWindow filters by the session's StartedAt timestamp.
	StartedWindow Window `json:"started_window,omitempty"`
	// HasIntervention, when non-nil, restricts to sessions that do
	// (true) / do not (false) have a pending intervention.
	HasIntervention *bool `json:"has_intervention,omitempty"`
	// HasFailedTask, when non-nil, restricts to sessions that do
	// (true) / do not (false) have a failed task.
	HasFailedTask *bool `json:"has_failed_task,omitempty"`
	// CostAboveCents, when non-nil, restricts to sessions whose
	// TotalCostCents is strictly above this threshold.
	CostAboveCents *int64 `json:"cost_above_cents,omitempty"`
	// Query is a free-text substring filter over session id + agent
	// name + user. When non-empty, the runtime forwards it to the
	// `search.sessions` index (Brief 11 §CC-4) and the SessionFilter
	// axes are post-search refinements (D-122 — forward then filter).
	Query string `json:"query,omitempty"`
}

type SessionRow struct {
	// SessionID is the stable session identifier.
	SessionID string `json:"session_id"`
	// Status is the session's lifecycle status.
	Status SessionStatus `json:"status"`
	// AgentID is the registered agent identifier the session ran under
	// ("" when no agent is bound).
	AgentID string `json:"agent_id"`
	// AgentName is the planner-facing agent display name.
	AgentName string `json:"agent_name"`
	// UserID is the user component of the session's identity triple.
	UserID string `json:"user_id"`
	// TenantID is the tenant component of the session's identity triple.
	TenantID string `json:"tenant_id"`
	// StartedAt is the session-open timestamp.
	StartedAt time.Time `json:"started_at"`
	// LastActivityAt is the timestamp of the most-recent activity.
	LastActivityAt time.Time `json:"last_activity_at"`
	// Duration is the elapsed span (LastActivityAt-StartedAt for closed
	// sessions, now-StartedAt for live ones). Marshalled as int64
	// nanoseconds (Go's time.Duration JSON form).
	Duration time.Duration `json:"duration"`
	// TasksCount is the number of tasks the session has spawned.
	TasksCount int `json:"tasks_count"`
	// EventsCount is the number of events the session has emitted.
	EventsCount int `json:"events_count"`
	// TotalCostCents is the session's accumulated LLM cost in US cents.
	TotalCostCents int64 `json:"total_cost_cents"`
	// TotalTokens is the session's accumulated LLM token count.
	TotalTokens int64 `json:"total_tokens"`
	// HasPendingIntervention reports whether the session has a pause
	// awaiting resume / approval.
	HasPendingIntervention bool `json:"has_pending_intervention"`
	// HasFailedTask reports whether the session has at least one failed
	// task.
	HasFailedTask bool `json:"has_failed_task"`
	// Identity is the impersonation triplet (Phase 72b / D-107). When
	// the session is a normal non-impersonated run, only the top-level
	// Tenant/User/Session carry meaning and Impersonating is nil; when
	// the session is an admin-initiated impersonated run, Actor carries
	// the verified admin identity and Impersonating carries the target
	// identity the run executed under. The Console Sessions-page
	// Identity column renders the Actor triple plus a separate
	// `impersonating` chip when Impersonating is non-empty.
	Identity IdentityScope `json:"identity"`
}

type SessionSort string

type SessionStatus string

type SessionsInspectRequest struct {
	// Identity is the (tenant, user, session) scope. Mandatory.
	Identity IdentityScope `json:"identity"`
	// SessionID is the session to inspect.
	SessionID string `json:"session_id"`
}

type SessionsInspectResponse struct {
	// Row is the session's catalog-row projection (same shape as a
	// `sessions.list` row).
	Row SessionRow `json:"row"`
	// RecentInterventions is the capped slice of recent interventions
	// (≤ MaxSessionInterventionSummaries), most-recent first.
	RecentInterventions []InterventionSummary `json:"recent_interventions"`
	// RecentArtifacts is the capped slice of recent artifacts
	// (≤ MaxSessionArtifactSummaries), most-recent first.
	RecentArtifacts []ArtifactRefSummary `json:"recent_artifacts"`
}

type SessionsListRequest struct {
	// Identity is the (tenant, user, session) scope the listing is
	// projected for. Mandatory — an incomplete triple fails closed.
	Identity IdentityScope `json:"identity"`
	// Filter is the optional facet filter; the zero value lists every
	// visible session.
	Filter SessionFilter `json:"filter"`
	// Sort selects the row ordering; an empty value applies
	// SessionSortStartedDesc.
	Sort SessionSort `json:"sort,omitempty"`
	// Cursor is the opaque pagination cursor returned by a previous
	// SessionsListResponse.NextCursor. Empty starts from the first page.
	Cursor string `json:"cursor,omitempty"`
	// Limit is the rows-per-page; a non-positive value applies
	// DefaultSessionListLimit. A value above MaxSessionListLimit is a
	// 400 (CodeInvalidRequest) — never a silent clamp.
	Limit int `json:"limit,omitempty"`
}

type SessionsListResponse struct {
	// Rows is the page of session rows, in the requested sort order.
	Rows []SessionRow `json:"rows"`
	// NextCursor is the opaque cursor for the next page; "" when this
	// is the last page.
	NextCursor string `json:"next_cursor"`
	// Truncated is true when the candidate set hit Limit+1 rows — the
	// honest "there are more" signal, NEVER a silent exact total.
	Truncated bool `json:"truncated"`
}

type SizeRange struct {
	// MinBytes, when set, excludes artifacts strictly smaller than it.
	MinBytes *int64 `json:"min_bytes,omitempty"`
	// MaxBytes, when set, excludes artifacts strictly larger than it.
	MaxBytes *int64 `json:"max_bytes,omitempty"`
}

type StartRequest struct {
	// Identity is the request's identity scope. The triple is mandatory;
	// Run is ignored (a `start` mints the run). Scope is ignored.
	Identity IdentityScope `json:"identity"`
	// Query is the user-facing query that starts the run. Optional —
	// some runs are kicked off without a natural-language query.
	Query string `json:"query,omitempty"`
	// Description is an operator-facing description of the task.
	// Optional.
	Description string `json:"description,omitempty"`
	// Priority is the task's initial scheduling priority. Zero is the
	// default priority.
	Priority int `json:"priority,omitempty"`
	// IdempotencyKey, when non-empty, deduplicates the spawn: a second
	// `start` with the same key (namespaced by session) returns the
	// existing task handle with Reused=true. Empty disables dedup.
	IdempotencyKey string `json:"idempotency_key,omitempty"`
	// InputArtifactIDs (Round-7 F11 / D-166) attach operator-uploaded
	// artifacts as multimodal inputs the run consumes on its first
	// planner turn. The runtime's per-MIME materializer routes each
	// id: `image/*` bytes inline as `ImagePart.DataURL`; everything
	// else stays an `ArtifactStub` the LLM routes through the tool
	// catalog. The Playground composer's chat-attach control plumbs
	// uploaded ids through this field. Empty is the text-only default.
	InputArtifactIDs []string `json:"input_artifact_ids,omitempty"`
}

type StartResponse struct {
	// TaskID is the runtime-assigned task identifier for the spawned
	// (or, on an idempotency-key match, the existing) task.
	TaskID string `json:"task_id"`
	// Reused is true when an IdempotencyKey match returned an existing
	// task rather than spawning a fresh one.
	Reused bool `json:"reused"`
	// ProtocolVersion echoes the Protocol version the Runtime answered
	// under so a client can detect a version skew.
	ProtocolVersion string `json:"protocol_version"`
}

type SubsystemDriver struct {
	// Subsystem names the persistence-shaped subsystem ("state",
	// "artifacts", "memory", "eventlog").
	Subsystem string `json:"subsystem"`
	// Driver is the configured driver name ("inmem", "sqlite",
	// "postgres", ...). Never the DSN / connection string — only the
	// driver name leaks across the Protocol boundary.
	Driver string `json:"driver"`
	// Mode is an optional posture detail ("readwrite", "readonly",
	// "embedded"). Empty when the subsystem reports none.
	Mode string `json:"mode,omitempty"`
}

type SubsystemHealth struct {
	// Subsystem names the runtime subsystem (e.g. "events", "state",
	// "tasks").
	Subsystem string `json:"subsystem"`
	// Status is the structural readiness — one of "ready", "degraded",
	// or "unavailable". Read from the subsystem's own posture seam, not
	// from a synthetic deep-check probe.
	Status string `json:"status"`
	// Detail is an optional human-readable explanation — populated for
	// a degraded / unavailable subsystem with the reason.
	Detail string `json:"detail,omitempty"`
}

type TaskCostRollup struct {
	// TotalTokens is the total token count (prompt + output).
	TotalTokens int64 `json:"total_tokens"`
	// PromptTokens is the prompt-side token count.
	PromptTokens int64 `json:"prompt_tokens"`
	// OutputTokens is the output-side token count.
	OutputTokens int64 `json:"output_tokens"`
	// USD is the total dollar cost.
	USD float64 `json:"usd"`
	// PerStep is the cost breakdown, one entry per planner step.
	PerStep []TaskCostStep `json:"per_step"`
}

type TaskCostStep struct {
	// StepIndex is the 0-based planner-step index.
	StepIndex int `json:"step_index"`
	// Tokens is the total token count attributed to the step.
	Tokens int64 `json:"tokens"`
	// USD is the dollar cost attributed to the step.
	USD float64 `json:"usd"`
}

type TaskDetail struct {
	// Task is the compact row projection (same shape `tasks.list`
	// returns).
	Task TaskRow `json:"task"`
	// ParentSession is the parent-session reference card.
	ParentSession TaskParentSessionRef `json:"parent_session"`
	// ParentTask is the parent-task reference; nil when the task is not
	// a child of a SpawnTask group.
	ParentTask *TaskParentTaskRef `json:"parent_task,omitempty"`
	// Cost is the per-task cost rollup aggregated from
	// `llm.cost.recorded` events scoped to the task.
	Cost TaskCostRollup `json:"cost"`
	// PlannerSnapshot is the planner-checkpoint reference at spawn time;
	// nil when no checkpoint exists.
	PlannerSnapshot *TaskPlannerSnapshotRef `json:"planner_snapshot,omitempty"`
	// ResultRef references the task's result payload by artifact stub
	// when the result exceeds the heavy-content threshold (D-026); nil
	// when the task has no result or the result is inlined small.
	ResultRef *ArtifactRef `json:"result_ref,omitempty"`
	// ResultInline carries the task's result payload directly when it is
	// below the heavy-content threshold ("" when absent or referenced).
	ResultInline string `json:"result_inline,omitempty"`
	// Trajectory is the projected planner reasoning-trace snapshot;
	// nil when the trajectory is unavailable (evicted or not captured).
	Trajectory *TaskTrajectoryRef `json:"trajectory,omitempty"`
}

type TaskFilter struct {
	// Statuses restricts to tasks whose Status is in this set.
	Statuses []TaskStatus `json:"statuses,omitempty"`
	// Kinds restricts to tasks whose Kind is in this set; empty matches
	// both foreground and background.
	Kinds []TaskKind `json:"kinds,omitempty"`
	// ParentTaskID drills into a SpawnTask group — restricts to tasks
	// whose ParentTaskID equals this value ("" = no parent-task filter).
	ParentTaskID string `json:"parent_task_id,omitempty"`
	// Identities scopes the query. A query naming more than one distinct
	// tenant is a cross-tenant fan-in and requires the `auth.ScopeAdmin`
	// claim (D-079). Empty = the caller's own identity scope.
	Identities []IdentityScope `json:"identities,omitempty"`
	// Since is an optional lower bound on StartedAt (zero = unbounded).
	Since time.Time `json:"since,omitempty"`
	// Until is an optional upper bound on StartedAt (zero = unbounded).
	Until time.Time `json:"until,omitempty"`
	// ErrorClasses facets on TaskRow.ErrorClass for Failed tasks.
	ErrorClasses []string `json:"error_classes,omitempty"`
	// LatencyAboveMS facets on DurationMS — restricts to tasks whose
	// DurationMS is at or above this value (0 = no latency filter).
	LatencyAboveMS int64 `json:"latency_above_ms,omitempty"`
	// Search is a free-text substring filter over the task's
	// description + query, routed to the runtime search.tasks index.
	Search string `json:"search,omitempty"`
	// GroupID drills into one `TaskGroup` — restricts to tasks whose
	// GroupID equals this value ("" = no group filter). The Background
	// Jobs page's per-job right-rail "Related Sessions" tab issues a
	// `tasks.list` with this facet set to surface the sibling tasks
	// (foreground + background) under the same group. Identity scope is
	// still enforced — a cross-tenant `group_id` lookup never widens
	// visibility. Phase 73h (D-128).
	GroupID string `json:"group_id,omitempty"`
	// HasPendingApproval, when non-nil, restricts to tasks whose
	// HasPendingApproval row field equals the pointee. nil = no
	// approval filter; *true = only tasks with an open approval gate;
	// *false = only tasks with none. The Background Jobs page's `Has
	// pending approval` facet chip binds this. Phase 73h (D-128).
	HasPendingApproval *bool `json:"has_pending_approval,omitempty"`
}

type TaskGetRequest struct {
	// Identity is the (tenant, user, session) scope. Mandatory.
	Identity IdentityScope `json:"identity"`
	// ID is the task identifier to project.
	ID string `json:"id"`
}

type TaskKind string

type TaskListAggregates struct {
	// Pending is the count of filtered tasks in the Pending column.
	Pending int64 `json:"pending"`
	// Running is the count of filtered tasks in the Running column.
	Running int64 `json:"running"`
	// Paused is the count of filtered tasks in the Paused column.
	Paused int64 `json:"paused"`
	// Failed is the count of filtered tasks in the Failed column.
	Failed int64 `json:"failed"`
	// Complete is the count of filtered tasks in the Done column.
	Complete int64 `json:"complete"`
	// Cancelled is the count of filtered tasks that were cancelled.
	Cancelled int64 `json:"cancelled"`
}

type TaskListCursor struct {
	// NextPageToken is the opaque continuation token; empty when there
	// are no more pages.
	NextPageToken string `json:"next_page_token,omitempty"`
}

type TaskListRequest struct {
	// Identity is the (tenant, user, session) scope the task list is
	// projected for. Mandatory — an incomplete triple fails closed.
	Identity IdentityScope `json:"identity"`
	// Filter is the optional facet filter; the zero value lists every
	// visible task.
	Filter TaskFilter `json:"filter"`
	// PageSize is the rows-per-page; a non-positive value applies
	// DefaultTaskListPageSize. A value above MaxTaskListPageSize is a
	// 400 (CodeInvalidRequest) — never a silent clamp.
	PageSize int `json:"page_size,omitempty"`
	// Cursor is the pagination cursor; the zero value requests the
	// first page.
	Cursor TaskListCursor `json:"cursor"`
	// IncludeStatusCounterStrip opts the response into carrying the
	// Phase 73b (D-126) TasksListStatusCounterStrip aggregate. It is
	// off by default — the Console Live Runtime page sets it on its
	// initial-load `tasks.list` call and then maintains the strip live
	// from the `task.*` SSE stream (the aggregate is the initial-load
	// shape only; see the phase-73b plan's "tasks.list aggregate cost"
	// risk). The Tasks page (73d) never sets it — its kanban renders
	// the filtered-view TaskListAggregates instead.
	IncludeStatusCounterStrip bool `json:"include_status_counter_strip,omitempty"`
}

type TaskListResponse struct {
	// Rows is the page of task rows, sorted by StartedAt descending
	// (newest first).
	Rows []TaskRow `json:"rows"`
	// Cursor carries the continuation token for the next page.
	Cursor TaskListCursor `json:"cursor"`
	// Aggregates carries the per-status counters for the filtered view.
	Aggregates TaskListAggregates `json:"aggregates"`
	// StatusCounterStrip carries the Phase 73b (D-126) header-strip
	// aggregate — non-nil ONLY when the request set
	// IncludeStatusCounterStrip. It is computed over the FULL identity-
	// scoped task set (not the filtered view) and is the Console Live
	// Runtime page's header five-chip strip. nil on a request that did
	// not opt in (the Tasks page never opts in).
	StatusCounterStrip *TasksListStatusCounterStrip `json:"status_counter_strip,omitempty"`
}

type TaskParentSessionRef struct {
	// SessionID is the parent session's identifier.
	SessionID string `json:"session_id"`
	// AgentName is the agent the session runs.
	AgentName string `json:"agent_name"`
	// Status is the parent session's lifecycle status.
	Status string `json:"status"`
	// StartedAt is the parent session's start timestamp.
	StartedAt time.Time `json:"started_at"`
	// LatestEventAt is the timestamp of the most recent event on the
	// parent session.
	LatestEventAt time.Time `json:"latest_event_at"`
}

type TaskParentTaskRef struct {
	// TaskID is the spawning task's identifier.
	TaskID string `json:"task_id"`
	// Kind is the spawning task's kind.
	Kind TaskKind `json:"kind"`
	// Status is the spawning task's lifecycle status.
	Status TaskStatus `json:"status"`
}

type TaskPlannerSnapshotRef struct {
	// CheckpointID is the planner-checkpoint identifier (resolvable via
	// state.load_planner_checkpoint).
	CheckpointID string `json:"checkpoint_id"`
	// Summary is the pre-truncated checkpoint summary.
	Summary string `json:"summary"`
}

type TaskRow struct {
	// ID is the unified task identifier (foreground run or background
	// task; one TaskID namespace).
	ID string `json:"id"`
	// Kind discriminates foreground vs background.
	Kind TaskKind `json:"kind"`
	// Status is the task's lifecycle state.
	Status TaskStatus `json:"status"`
	// Priority is the TASK-level priority (D-072 — the `prioritize`
	// control method). NEVER a session-level priority (D-065 carve-out).
	Priority int `json:"priority"`
	// Identity is the (tenant, user, session) triple the task runs
	// within — the Console truncates it for display on the card.
	Identity IdentityScope `json:"identity"`
	// ParentSessionID is the session the task belongs to.
	ParentSessionID string `json:"parent_session_id"`
	// ParentTaskID is set when the task was spawned by a planner
	// `SpawnTask` — it names the spawning task ("" when not a child).
	ParentTaskID string `json:"parent_task_id,omitempty"`
	// Description is the planner-facing task summary.
	Description string `json:"description"`
	// Query is the originating query / prompt text.
	Query string `json:"query"`
	// StartedAt is the task's creation timestamp.
	StartedAt time.Time `json:"started_at"`
	// UpdatedAt is the timestamp of the most recent lifecycle transition.
	UpdatedAt time.Time `json:"updated_at"`
	// DurationMS is the elapsed wall-clock time in milliseconds
	// (StartedAt → UpdatedAt).
	DurationMS int64 `json:"duration_ms"`
	// ErrorClass is the short failure-class string; set only when
	// Status is "failed" ("" otherwise).
	ErrorClass string `json:"error_class,omitempty"`
	// ToolCount is the count of child tool tasks spawned by this task.
	ToolCount int `json:"tool_count"`
	// BackgroundAcknowledged latches true once a completed background
	// task has been acknowledged (the `task.background_acknowledged`
	// event).
	BackgroundAcknowledged bool `json:"background_acknowledged"`
	// GroupID is the TaskGroup the task is a member of ("" when the
	// task is not a group member).
	GroupID string `json:"group_id,omitempty"`
	// Progress is the planner-emitted numeric progress hint in the
	// [0,1] range. It is a pointer so the wire shape distinguishes "the
	// planner emitted progress 0.0" from "the planner emitted no
	// progress at all" — nil ⇒ no hint, and the Console renders an
	// indeterminate Progress mini-bar rather than a 0% bar. Phase 73h
	// (D-128): the Background Jobs page's Progress column.
	Progress *float64 `json:"progress,omitempty"`
	// Tags is the slice of short labels the Background Jobs page renders
	// in its Tags column — the parent task type plus any planner-emitted
	// labels. Empty slice ⇒ no tags. Phase 73h (D-128).
	Tags []string `json:"tags,omitempty"`
	// LastActivityAt is the timestamp of the most recent activity on the
	// task — the max of UpdatedAt and any event on the run's stream. The
	// Background Jobs page's `Stuck > 1h` saved-filter chip derives off
	// this field (a Console-local rule — D-061). Phase 73h (D-128).
	LastActivityAt time.Time `json:"last_activity_at"`
	// IsBackground mirrors `Kind == "background"` — a convenience
	// boolean so a Console row-renderer branches without re-comparing
	// the enum. Phase 73h (D-128): the Background Jobs queue is the
	// `IsBackground == true` projection of the unified task set.
	IsBackground bool `json:"is_background"`
	// HasPendingApproval is true when the task's run has at least one
	// open HITL approval / tool-approval gate. The Background Jobs
	// page's `Has pending approval` facet filters on it, and the
	// per-job right-rail's Pending-approvals tab is populated when it is
	// true. Phase 73h (D-128).
	HasPendingApproval bool `json:"has_pending_approval"`
}

type TaskStatus string

type TaskTrajectoryRef struct {
	Steps []TaskTrajectoryStep `json:"steps"`
}

type TaskTrajectoryStep struct {
	Index          int    `json:"index"`
	ReasoningTrace string `json:"reasoning_trace"`
}

type TasksListStatusCounterStrip struct {
	// Pending is the count of identity-scoped tasks in the Pending state.
	Pending int `json:"pending"`
	// Running is the count of identity-scoped tasks in the Running state.
	Running int `json:"running"`
	// Completed is the count of identity-scoped tasks in the Complete
	// state (the strip's `completed` chip — see the type godoc on the
	// `complete` → `completed` vocabulary choice).
	Completed int `json:"completed"`
	// Paused is the count of identity-scoped tasks in the Paused state.
	Paused int `json:"paused"`
	// Failed is the count of identity-scoped tasks in the Failed state.
	Failed int `json:"failed"`
}

type TimeRange struct {
	// After, when non-zero, excludes artifacts created strictly before
	// it.
	After time.Time `json:"after,omitempty"`
	// Before, when non-zero, excludes artifacts created strictly after
	// it.
	Before time.Time `json:"before,omitempty"`
}

type Tool struct {
	// ID is the stable catalog key (the tool's registered name).
	ID string `json:"id"`
	// Name is the planner-facing display name (equal to ID in V1).
	Name string `json:"name"`
	// Version is the tool descriptor version string ("" when unset).
	Version string `json:"version"`
	// Description is the planner-facing summary.
	Description string `json:"description"`
	// Scope is the tool's visibility scope: "tenant" | "agent" | "session".
	Scope string `json:"scope"`
	// Transport discriminates the tool's source.
	Transport ToolTransport `json:"transport"`
	// OAuthStatus is the tool's OAuth binding status.
	OAuthStatus ToolOAuthStatus `json:"oauth_status"`
	// ApprovalPolicy is the tool's HITL approval gate.
	ApprovalPolicy ToolApprovalPolicy `json:"approval_policy"`
	// ReliabilityTier is the operator-facing reliability label
	// (derived from the tool's side-effect class / cost hint).
	ReliabilityTier string `json:"reliability_tier"`
	// Owner is the configured owner / source identifier ("" when unset).
	Owner string `json:"owner"`
	// LastUsedAt is the timestamp of the most recent invocation; the
	// zero value means "never used".
	LastUsedAt time.Time `json:"last_used_at"`
}

type ToolAggregates struct {
	// Total is the count of tools matching the filter.
	Total int64 `json:"total"`
	// Active is the count of tools with a non-zero LastUsedAt.
	Active int64 `json:"active"`
	// PendingApproval is the count of tools whose ApprovalPolicy is
	// "gated".
	PendingApproval int64 `json:"pending_approval"`
	// AwaitingOAuth is the count of tools whose OAuthStatus is
	// "Required" or "Expired".
	AwaitingOAuth int64 `json:"awaiting_oauth"`
}

type ToolApprovalPolicy string

type ToolContentBucket struct {
	// MaxBytes is the inclusive upper bound of this bucket in bytes.
	MaxBytes int64 `json:"max_bytes"`
	// Count is the number of recent results that fell in this bucket.
	Count int64 `json:"count"`
}

type ToolContentStats struct {
	// ID echoes the requested tool ID.
	ID string `json:"id"`
	// Histogram is the result-size distribution, one bucket per
	// power-of-two byte range, ascending.
	Histogram []ToolContentBucket `json:"histogram"`
	// HeavyThresholdBytes is the configured heavy-content threshold
	// (D-026) — results at or above this size route through the
	// ArtifactStore by-reference.
	HeavyThresholdBytes int64 `json:"heavy_threshold_bytes"`
	// HeavyCount is the number of recent results at or above the
	// heavy-content threshold.
	HeavyCount int64 `json:"heavy_count"`
	// NegotiatedDisplay maps a MIME type to its negotiated MCP-Apps
	// DisplayMode (D-062); empty for non-MCP tools.
	NegotiatedDisplay map[string]string `json:"negotiated_display"`
}

type ToolContentStatsRequest struct {
	// Identity is the (tenant, user, session) scope. Mandatory.
	Identity IdentityScope `json:"identity"`
	// ID is the catalog key of the tool to report content stats for.
	ID string `json:"id"`
}

type ToolDescribeRequest struct {
	// Identity is the (tenant, user, session) scope. Mandatory.
	Identity IdentityScope `json:"identity"`
	// ID is the catalog key of the tool to describe.
	ID string `json:"id"`
}

type ToolFilter struct {
	// Scopes restricts to tools whose Scope is in this set.
	Scopes []string `json:"scopes,omitempty"`
	// Transports restricts to tools whose Transport is in this set.
	Transports []ToolTransport `json:"transports,omitempty"`
	// OAuthStatuses restricts to tools whose OAuthStatus is in this set.
	OAuthStatuses []ToolOAuthStatus `json:"oauth_statuses,omitempty"`
	// ApprovalPolicies restricts to tools whose ApprovalPolicy is in this set.
	ApprovalPolicies []ToolApprovalPolicy `json:"approval_policies,omitempty"`
	// ReliabilityTiers restricts to tools whose ReliabilityTier is in this set.
	ReliabilityTiers []string `json:"reliability_tiers,omitempty"`
	// Search is a free-text substring filter over tool name + version.
	Search string `json:"search,omitempty"`
}

type ToolGetRequest struct {
	// Identity is the (tenant, user, session) scope. Mandatory.
	Identity IdentityScope `json:"identity"`
	// ID is the catalog key of the tool to project.
	ID string `json:"id"`
}

type ToolListRequest struct {
	// Identity is the (tenant, user, session) scope the catalog is
	// projected for. Mandatory — an incomplete triple fails closed.
	Identity IdentityScope `json:"identity"`
	// Filter is the optional facet filter; the zero value lists every
	// visible tool.
	Filter ToolFilter `json:"filter"`
	// Page is the 1-based page index; a non-positive value means page 1.
	Page int `json:"page,omitempty"`
	// PageSize is the rows-per-page; a non-positive value applies
	// DefaultToolListPageSize. A value above MaxToolListPageSize is a
	// 400 (CodeInvalidRequest) — never a silent clamp.
	PageSize int `json:"page_size,omitempty"`
}

type ToolListResponse struct {
	// Tools is the page of catalog rows, sorted by Name.
	Tools []Tool `json:"tools"`
	// 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 for the filtered view.
	PageCount int `json:"page_count"`
	// TotalRows is the total row count for the filtered view.
	TotalRows int64 `json:"total_rows"`
	// Aggregates carries the four catalog counters for the filtered view.
	Aggregates ToolAggregates `json:"aggregates"`
}

type ToolManifest struct {
	// Tool is the catalog-row projection (same shape as `tools.get`).
	Tool Tool `json:"tool"`
	// SideEffect is the declared side-effect class
	// ("pure" | "read" | "write" | "external" | "stateful").
	SideEffect string `json:"side_effect"`
	// ArgsSchema is the raw JSON-Schema (object) for the tool's
	// argument shape, as a JSON string ("" when the tool declares none).
	ArgsSchema string `json:"args_schema"`
	// OutSchema is the raw JSON-Schema (object) for the tool's result
	// shape, as a JSON string ("" when the tool declares none).
	OutSchema string `json:"out_schema"`
	// Examples carries the canonical argument-shape examples, each a
	// JSON string.
	Examples []string `json:"examples"`
	// AuthScopes lists the scopes a planner step's identity must carry
	// for the tool to be visible.
	AuthScopes []string `json:"auth_scopes"`
	// OAuthBindingScope is the tool's OAuth binding scope per D-083
	// ("user" | "agent" | "" when the tool requires no OAuth).
	OAuthBindingScope string `json:"oauth_binding_scope"`
	// RetryAttempts is the reliability shell's configured retry budget
	// (D-024).
	RetryAttempts int `json:"retry_attempts"`
	// TimeoutMS is the reliability shell's per-attempt timeout in
	// milliseconds (0 when the policy applies its default).
	TimeoutMS int64 `json:"timeout_ms"`
	// LoadingMode is the prompt-time loading mode ("always" | "deferred").
	LoadingMode string `json:"loading_mode"`
	// DisplayModes maps a MIME type to its negotiated MCP-Apps
	// DisplayMode (D-062); empty for non-MCP tools.
	DisplayModes map[string]string `json:"display_modes"`
}

type ToolMetrics struct {
	// ID echoes the requested tool ID.
	ID string `json:"id"`
	// Window echoes the resolved observation window.
	Window ToolMetricsWindow `json:"window"`
	// ErrorRate1h is the fraction of failed invocations over the last 1h.
	ErrorRate1h float64 `json:"error_rate_1h"`
	// ErrorRate24h is the fraction of failed invocations over the last 24h.
	ErrorRate24h float64 `json:"error_rate_24h"`
	// ErrorRate7d is the fraction of failed invocations over the last 7d.
	ErrorRate7d float64 `json:"error_rate_7d"`
	// Invocations is the total invocation count over the selected window.
	Invocations int64 `json:"invocations"`
	// Failures is the failed-invocation count over the selected window.
	Failures int64 `json:"failures"`
	// Status is the health pill for the selected window.
	Status ToolStatus `json:"status"`
}

type ToolMetricsRequest struct {
	// Identity is the (tenant, user, session) scope. Mandatory.
	Identity IdentityScope `json:"identity"`
	// ID is the catalog key of the tool to report metrics for.
	ID string `json:"id"`
	// Window selects the observation window; an empty value applies
	// ToolWindow1h.
	Window ToolMetricsWindow `json:"window,omitempty"`
}

type ToolMetricsWindow string

type ToolOAuthStatus string

type ToolRevokeOAuthRequest struct {
	// Identity is the (tenant, user, session) scope. Mandatory.
	Identity IdentityScope `json:"identity"`
	// ID is the catalog key of the tool whose OAuth bindings to revoke.
	ID string `json:"id"`
}

type ToolRevokeOAuthResponse struct {
	// ID echoes the tool ID whose bindings were revoked.
	ID string `json:"id"`
	// RevokedCount is the number of OAuth bindings revoked.
	RevokedCount int64 `json:"revoked_count"`
}

type ToolSetApprovalPolicyRequest struct {
	// Identity is the (tenant, user, session) scope. Mandatory.
	Identity IdentityScope `json:"identity"`
	// ID is the catalog key of the tool to update.
	ID string `json:"id"`
	// Policy is the new approval policy; must be a valid
	// ToolApprovalPolicy or the request is rejected with
	// CodeInvalidRequest.
	Policy ToolApprovalPolicy `json:"policy"`
}

type ToolSetApprovalPolicyResponse struct {
	// ID echoes the updated tool ID.
	ID string `json:"id"`
	// Policy echoes the applied approval policy.
	Policy ToolApprovalPolicy `json:"policy"`
}

type ToolStatus string

type ToolTransport string

type TopologyEdge struct {
	// From is the upstream node's Name.
	From string `json:"from"`
	// To is the downstream node's Name.
	To string `json:"to"`
	// QueueDepth is the number of envelopes currently buffered on the
	// (From → To) channel — len(channel) at projection time.
	QueueDepth int `json:"queue_depth"`
	// QueueCapacity is the bounded buffer size of the (From → To)
	// channel — cap(channel). A consumer renders QueueDepth /
	// QueueCapacity as a saturation indicator.
	QueueCapacity int `json:"queue_capacity"`
}

type TopologyNode struct {
	// Name is the node's unique identifier within the engine.
	Name string `json:"name"`
	// Kind is the node's role tag — inlet / node / outlet.
	Kind TopologyNodeKind `json:"kind"`
}

type TopologyNodeKind string

type TopologyProjection struct {
	// EngineID identifies the engine the projection describes. In V1
	// (one engine per Runtime process) it is the Runtime's engine id;
	// the field exists so a post-V1 multi-engine Runtime can scope a
	// projection without a wire-shape break.
	EngineID string `json:"engine_id"`
	// OccurredAt is the wall-clock instant the projection was built.
	// On the `topology.changed` event it is the construction / edge-
	// change time; on a `topology.snapshot` reply it is the snapshot
	// time.
	OccurredAt time.Time `json:"occurred_at"`
	// Nodes is the engine's node set, sorted lexicographically by Name
	// for byte-stability across snapshots of the same engine.
	Nodes []TopologyNode `json:"nodes"`
	// Edges is the engine's directed edge set, sorted lexicographically
	// by (From, To) for byte-stability.
	Edges []TopologyEdge `json:"edges"`
}

type TopologySnapshotRequest struct {
	// Identity is the mandatory caller identity scope. An incomplete
	// triple fails the request closed with CodeIdentityRequired.
	Identity IdentityScope `json:"identity"`
}

type Version struct {
	// Major is bumped on a breaking Protocol change. Two versions are
	// Compatible iff their Major components are equal.
	Major int
	// Minor is bumped on a backward-compatible surface addition (a new
	// method, a new capability, a new optional wire field).
	Minor int
	// Patch is bumped on a backward-compatible fix with no surface
	// change.
	Patch int
}

type VersionHandshake struct {
	// ProtocolVersion is the version string the Runtime speaks — the
	// ProtocolVersion constant. A client parses it (ParseVersion) and
	// checks Compatible against its own.
	ProtocolVersion string `json:"protocol_version"`
	// Capabilities is the set of Protocol surfaces the Runtime
	// advertises as live — deterministically sorted (Capabilities()).
	Capabilities []Capability `json:"capabilities"`
}

type Window struct {
	// From is the inclusive lower bound; nil ⇒ unbounded below.
	From *time.Time `json:"from,omitempty"`
	// To is the inclusive upper bound; nil ⇒ unbounded above.
	To *time.Time `json:"to,omitempty"`
}