mcp

type AppAvailablePayload struct {
	events.SafeSealed
	// Identity scopes the discovery to the (tenant, user, session) triple
	// the tool ran under; its RunID is the turn-correlation key.
	Identity identity.Quadruple
	// ServerID is the MCP server (source id) hosting the app — the value a
	// client passes to mcp.servers.read_resource to fetch the document.
	ServerID tools.ToolSourceID
	// ToolCallID is the stable per-invocation id (a content hash, not a
	// counter) the client passes to mcp.apps.tool_context to fetch the tool
	// context — the input + lowered result — that produced this app. Safe
	// by construction: an opaque hash, never caller content. EMPTY when no
	// context was captured for the invocation (no capturer wired, or the
	// capture failed): a non-empty id promises a fetchable record, so a
	// client may treat a miss as an expired one and say so.
	ToolCallID string
	// ToolName is the server-side tool name that declared the app — display
	// metadata only. Safe by construction: a tool name, never content.
	ToolName string
	// ResourceURI is the `ui://`-scheme URI of the app's UI document.
	ResourceURI string
	// DisplayMode is the display-mode hint (one of inline / fullscreen /
	// pip), or empty when the server stated none. The tool-definition
	// binding carries no mode in the canonical dialect, so this is empty on
	// the golden path and the renderer defaults to inline; a server MAY
	// supply a per-result hint that wins over the binding.
	DisplayMode string
	// RawHTMLTrusted is the raw-HTML trust posture carried on the
	// discovery. The driver emits the default-deny posture; a client
	// reconciles the full per-server trust via mcp.servers.get.
	RawHTMLTrusted bool
	// OccurredAt is the wall-clock instant the app was discovered.
	OccurredAt time.Time
}

type AppRef struct {
	// ResourceURI is the `ui://`-scheme URI of the app's UI document.
	// The host fetches the document via a resource read scoped to the
	// request identity triple. Its canonical source is the tool
	// definition's `_meta.ui.resourceUri`.
	ResourceURI string
	// PreferredDisplayMode is an optional display-mode hint (one of
	// inline / fullscreen / pip), or empty when none was stated. The tool
	// definition's `_meta.ui` carries no display mode in the canonical
	// dialect, so this is empty on the golden path; a server MAY supply a
	// per-result hint on the CallToolResult `_meta.ui` slot, which the
	// host merges over the binding. When empty, the renderer defaults to
	// inline. It is a hint only; the host reconciles it against the
	// server's negotiated capability set.
	PreferredDisplayMode string
	// ToolCallID is the stable, per-invocation identifier minted at the
	// tool-call site (a content hash of the run / server / tool / args).
	// It correlates a discovered app to the captured tool context — the
	// input + lowered result that produced it — so a Protocol client can
	// fetch that context via mcp.apps.tool_context. It is NOT parsed from
	// the server's `_meta` (a result never carries it).
	//
	// A non-empty value is a PROMISE that a context record was persisted:
	// the invocation path stamps it only after the capture succeeded, so it
	// stays empty when no capturer is wired or the capture failed. A reader
	// may therefore treat a fetch miss as "the record is gone" rather than
	// "it may never have existed".
	ToolCallID string
}

type ArtifactEgressedPayload struct {
	events.SafeSealed
	// Identity scopes the substitution to the (tenant, user, session)
	// triple the call ran under; its RunID correlates it to the turn.
	// The reachable artifact set was this triple's own and nothing wider.
	Identity identity.Quadruple
	// ServerID is the MCP server the bytes were sent to — the RECIPIENT,
	// which is what byte-eligibility governs and what this record makes
	// auditable.
	ServerID tools.ToolSourceID
	// ToolName is the server-side tool name that received the
	// substitution.
	ToolName string
	// Records is one entry per substituted parameter: the artifact id,
	// the parameter name, the byte count, and the `sha256:` digest that
	// says WHICH bytes moved without carrying them.
	Records []artifactegress.Record
	// OccurredAt is the wall-clock instant the substitution was made —
	// necessarily BEFORE the wire request, because the record is emitted
	// fail-closed ahead of it.
	OccurredAt time.Time
}

type AttachDeps struct {
	// Catalog receives one ToolDescriptor per discovered tool.
	Catalog tools.ToolCatalog
	// Registry receives the live Provider registration so observability
	// surfaces (the Console MCP Connections page) can project it.
	Registry *Registry
	// Bus carries the driver's mcp.* events. Mandatory — the driver's
	// own constructor validates it (mcp.resource_updated emission).
	Bus events.EventBus
	// Logger receives the per-server attachment Info line. Optional.
	Logger *slog.Logger
	// DefaultIdentity is the FALLBACK identity stamped on server-pushed
	// events that arrive without an inflight call (transport-side
	// notifications — Item 1). Per-call subscriptions
	// stamp the inflight caller's ctx-resident identity via the
	// driver's pushIdentity helper; this default only covers
	// transport-level events.
	DefaultIdentity identity.Identity
	// Closers is the caller's ordered closer chain. Attach appends the
	// Provider's Close immediately after a successful Connect so a
	// later Discover/Register failure still drains the live subprocess.
	Closers *[]func(context.Context) error
	// HostDisplayModes lists the MCP App (`io.modelcontextprotocol/ui`)
	// display modes the host can render. Projected onto the Provider's
	// Config.HostDisplayModes so the provider advertises the UI extension
	// during the initialize handshake. The boot loader sources this once
	// from the deployment-level `tools.mcp_app_host.display_modes` config
	// (defaulting to inline); empty leaves the SDK's default advertisement
	// untouched. This is the programmatic seam an embedder sets without YAML.
	HostDisplayModes []string
	// ToolContext is the optional MCP Apps tool-context capturer. When set,
	// the Provider persists the input + lowered result behind a declared
	// `ui://` app so the host can deliver it to the rendered app. A nil
	// capturer leaves tool-context delivery unwired (the host read returns
	// not-found). Optional.
	ToolContext ToolContextCapturer
	// Owner is the (tenant, agent) reconcile-view tag stamped on the
	// registry entry for a RUNTIME-ADDED connection. The boot loader leaves it
	// zero (boot-declared servers are untagged and never reconciled); the
	// runtime-add attach path sets a non-zero owner so the run-start reconcile
	// view scopes to it. It is a reconcile-view filter, never a dispatch or
	// isolation key.
	Owner auth.Owner
	// DescriptorFingerprint is the canonical digest of the NON-SECRET
	// runtime-added descriptor. It is retained on the live registration so
	// run-start reconciliation can distinguish an exact no-op from a same-name
	// descriptor replacement. Boot-declared attachments leave it empty.
	DescriptorFingerprint string
	// OAuthProviders is the declared OAuth-provider registry (keyed by the
	// non-secret provider NAME) Attach resolves a connection's
	// `oauth_provider` binding against. Populated by the runtime assembler
	// from its constructed provider map (and the devstack twin). A binding
	// naming a provider absent from this map fails the attach loud, listing
	// the registered names (§4.4 factory-error convention). Nil / empty is
	// valid when no connection binds a provider. The driver depends ONLY on
	// the `auth.OAuthProvider` interface — no concrete driver import (§13).
	OAuthProviders map[string]auth.OAuthProvider
	// OAuthProviderSet is the runtime provider SET a RUNTIME-ADDED connection's
	// `oauth_provider` binding resolves against, so a Protocol-installed
	// (owner-tagged) provider is bindable in addition to the boot map. When set
	// it TAKES PRECEDENCE over OAuthProviders (the set is seeded from the same
	// boot map at assembly, so boot providers stay resolvable). Optional — nil
	// leaves resolution on the OAuthProviders map (the boot catalog path). The
	// driver depends only on the narrow resolver interface (bare-name Get +
	// Names for the fail-loud message) — no concrete import.
	OAuthProviderSet OAuthProviderResolver
	// OAuthProviderOverride is a privately prepared provider used for this
	// attachment's named binding before it is published to the shared set.
	OAuthProviderOverride auth.OAuthProvider
	// OwnOAuthProvider transfers teardown ownership of the override to the MCP
	// provider. General provider-set bindings leave this false.
	OwnOAuthProvider bool
	// ToolAllowlist/ToolDenylist project a signed restrictive policy onto the
	// discovered tool descriptors before catalog publication.
	ToolAllowlist []string
	ToolDenylist  []string
	// ArtifactEgressMaxBytes bounds ONE substituted artifact value on one
	// outbound call for connections this attach wires. Sourced by the boot
	// loader (and the runtime attacher) from the deployment-level
	// `tools.mcp_artifact_egress_max_bytes`, which carries a documented
	// default. Zero resolves to config.DefaultMCPArtifactEgressMaxBytes so
	// an embedder that does not set it still gets a real ceiling rather
	// than an unbounded one. Optional.
	ArtifactEgressMaxBytes int
}

type AudioRef struct {
	Data     []byte
	MIMEType string
}

type AuthChallenge struct {
	// Scheme is the challenge auth scheme (e.g. "Bearer").
	Scheme string
	// ResourceMetadataURL is the RFC 9728 `resource_metadata` pointer, when
	// the challenge carried one.
	ResourceMetadataURL string
	// Realm is the optional `realm` challenge parameter.
	Realm string
	// Error is the optional RFC 6750 §3.1 `error` challenge parameter (e.g.
	// "insufficient_scope", "invalid_token"). Empty when the challenge
	// carried none.
	Error string
	// Scope is the optional RFC 6750 §3.1 `scope` challenge parameter — the
	// space-delimited scopes the downstream requires. Empty when absent.
	Scope string
	// Raw is the verbatim header value (provenance / debugging).
	Raw string
	// CapturedAt is the wall-clock instant the challenge was observed.
	CapturedAt time.Time
}

type CapturedToolContext struct {
	// ServerID is the MCP server (source id) the tool belongs to. Paired
	// with ToolCallID it forms the lookup key the host reads back through.
	ServerID tools.ToolSourceID
	// ToolCallID is the stable, collision-free per-invocation id minted by
	// ToolCallID (the content hash). It is the same value carried on the
	// discovery event and projected onto the app reference.
	ToolCallID string
	// Tool is the server-side tool name (display metadata only — the
	// lookup keys on ServerID + ToolCallID, never the tool name).
	Tool string
	// Input is the raw JSON argument object the tool was invoked with.
	Input json.RawMessage
	// Result is the JSON-encoded lowered tool result.
	Result json.RawMessage
	// IsError reports whether the tool returned a server-side error result.
	IsError bool
}

type Config struct {
	// Name is the unique source ID prefix. Empty rejects with
	// ErrInvalidConfig.
	Name string
	// TransportMode selects the wire transport. Empty defaults to
	// TransportAuto.
	TransportMode MCPTransportMode
	// URL is the endpoint for SSE / streamable-HTTP transports.
	// Required for those modes.
	URL string
	// Command is the argv-form subprocess command for the stdio
	// transport. [0] is the binary; [1:] are args. Required for
	// stdio. NEVER shell-form — the driver enforces this in
	// transport_stdio.go.
	Command []string
	// Headers are operator-supplied HTTP headers added to every
	// SSE / streamable-HTTP request (auth tokens, custom auth).
	// "URL connections require explicit headers for auth (no
	// implicit env passthrough)" — a settled security rule.
	Headers map[string]string
	// KeepAlive is the ping interval for the MCP session; zero
	// disables. The SDK's KeepAlive runs the underlying ping/pong.
	KeepAlive time.Duration
	// Logger is the per-provider slog logger. nil → a discard
	// logger; runtime never panics on absent Logger.
	Logger *slog.Logger
	// Bus is the event bus used to publish `mcp.resource_updated`
	// notifications. Required.
	Bus events.EventBus
	// ToolContext captures the tool context (input + lowered result) behind
	// a declared MCP App so the host can deliver it to the rendered app
	// (the MCP Apps "Data Delivery" lifecycle). Optional — a nil capturer
	// means tool-context delivery is not wired (the host's tool-context
	// read then returns not-found). When set, the driver calls it from the
	// tool-invocation path whenever a result declares a `ui://` app; a
	// Capture error is logged loudly but never fails the tool call.
	ToolContext ToolContextCapturer
	// DefaultPolicy is the ToolPolicy applied to descriptors built
	// from this provider. Zero-valued → tools.DefaultPolicy().
	DefaultPolicy tools.ToolPolicy
	// ToolPolicies are per-tool ToolPolicy overrides keyed by the
	// MCP server-side tool name (NOT the `<source>_<tool>` Harbor
	// name). When a discovered tool's name is present here, its
	// descriptor uses the override instead of DefaultPolicy; a tool
	// absent from the map falls back to DefaultPolicy.
	// Per-tool overrides apply to TOOLS only — MCP resources and
	// prompts always run under DefaultPolicy (the per-server default).
	//
	// Concurrent reuse: the map is read-only after New — it is
	// never mutated per-run. buildToolDescriptor only reads it, and
	// the resolved ToolPolicy is copied by value into each descriptor
	// at Discover time, so concurrent invocations of different tools
	// never share or race this map.
	ToolPolicies map[string]tools.ToolPolicy
	// DefaultIdentity is the fallback identity stamped on
	// transport-side events (notifications that arrive without an
	// inflight call). Required so the bus's ValidateEvent does not
	// reject the event when the SDK-supplied ctx carries no triple.
	//
	// the role narrows. For events the
	// SDK delivers WITH a populated ctx (per-call notifications
	// originating from an inflight tool / resource subscription),
	// the driver prefers `identity.From(ctx)` over this cached
	// default — `pushIdentity(ctx, cfg)` is the single helper that
	// implements the preference. The DefaultIdentity remains the
	// fallback for genuine transport-level events (a server-pushed
	// `notifications/resources/updated` arriving outside any
	// inflight call) where the ctx has no triple to read.
	DefaultIdentity identity.Identity

	// HostDisplayModes lists the MCP App (`io.modelcontextprotocol/ui`)
	// display modes this host can render. When non-empty, the provider
	// advertises the UI extension during the MCP initialize handshake with
	// these modes (filtered against the closed valid-mode set), so a server
	// can tailor the app references it returns to what the host actually
	// renders. Empty leaves the SDK's default capability advertisement
	// untouched (no UI extension) — the behaviour for an embedder that does
	// not opt in. The boot loader sources this from the deployment-level
	// `tools.mcp_app_host.display_modes` config (defaulting to inline), but
	// a programmatic embedder may set it directly. Read once at construction;
	// immutable thereafter.
	HostDisplayModes []string

	// OAuthProvider, when non-nil, binds this connection to a per-identity
	// OAuth credential source: every identity-stamped per-call RPC resolves a
	// fresh bearer via Token(ctx, source) and injects Authorization on THAT
	// request only. Nil leaves the connection on its static Headers (the
	// unbound default). Resolved once at construction from the operator's
	// non-secret provider NAME (config `oauth_provider`) against the declared
	// provider registry — the name selects an acquisition strategy; the
	// secret stays on the provider. Immutable after construction: no per-call
	// transport state mutates (the token rides the call's ctx). A pair-private
	// owned binding also authenticates preparation: each initialize attempt and
	// each discovery RPC resolves a bearer from that exact ctx before any wire
	// request, failing closed on an error or empty token. Shared boot bindings
	// retain credential-neutral connect/discovery for run-start reattachment.
	OAuthProvider auth.OAuthProvider
	// OwnOAuthProvider transfers teardown ownership of OAuthProvider to this
	// connection. It is reserved for a privately prepared signed capability;
	// ordinary boot/shared providers remain owned by their provider set.
	OwnOAuthProvider bool

	// MetaAnnotations is a static, non-secret set of operator-declared
	// key/values merged into the `_meta` map on every identity-stamped
	// per-call RPC, so a deployment can carry its own attribution vocabulary
	// to a shared server.
	//
	// Each KEY is a `_meta` PATH: a key with no `.` sets a top-level key, a
	// DOTTED key NESTS — the same interpretation, through the same helper
	// (injectMeta), that the credential-injection MetaKey has always had.
	// Reserved keys (the triple keys, `agent_id`, `traceparent`, `tracestate`,
	// and any `io.modelcontextprotocol/`-prefixed key) are rejected at config
	// / wire / attach validation — at the whole key AND at any dot-segment —
	// and can never shadow the triple or agent provenance (those are stamped
	// last). Colliding declared paths are rejected at validation and fail the
	// call with ErrMetaPathCollision if a legacy pair reaches the merge. Read
	// once at construction; immutable thereafter.
	MetaAnnotations map[string]string

	// OnAuthChallenge, when non-nil, is invoked whenever an MCP HTTP call to
	// this server answers `401` with a `WWW-Authenticate` Bearer challenge —
	// the MCP authorization spec's OAuth step-up. The callback records the
	// advertised OAuth requirement on the connection's registry state so an
	// operator can inspect it. Capture is pure observation: it never
	// retries, never attaches credentials, and never alters the call's error
	// semantics. Optional; nil disables challenge capture (stdio connections
	// never set it — the challenge is an HTTP-auth construct). Read once at
	// construction; immutable thereafter.
	OnAuthChallenge func(AuthChallenge)

	// OnScopeShortfall, when non-nil, is invoked whenever an MCP HTTP call
	// answers `403` with a `WWW-Authenticate` marking
	// `error="insufficient_scope"` (RFC 6750 §3.1) — a downstream step-up
	// scope shortfall. The callback records the parsed shortfall on the
	// connection's registry state so an operator can inspect the last
	// observed required-vs-granted gap. Best-effort observability: it never
	// retries, never widens a binding, and never alters the call's error
	// semantics (the per-call error enrichment rides a request-scoped ctx
	// slot instead). Optional; nil disables the registry-side record (stdio
	// connections never set it). Read once at construction; immutable
	// thereafter.
	OnScopeShortfall func(ScopeShortfall)

	// ToolOAuthProviders are per-entry OAuth-provider overrides keyed by the
	// MCP-side name (mirroring ToolPolicies' shape). An entry named here binds
	// THAT provider for every identity-stamped RPC that addresses by the entry's
	// key — a CallTool by tool name, a ReadResource / SubscribeResource by
	// resource URI, and a GetPrompt by prompt name; an unlisted key falls back
	// to OAuthProvider (the connection-level binding). Each entry was resolved +
	// validated against the same binding rules as OAuthProvider at attach time
	// (unknown name / stdio transport / static-Authorization conflict /
	// downstream-host allow-list). The map is a single per-entry namespace; a
	// key that would address more than one surface at once (a tool AND a prompt
	// of the same name) is rejected loud at discovery (ErrAmbiguousOAuthBinding),
	// never silently resolved by precedence. Read-only after New; the resolved
	// provider is read per-call from the call's own addressing key, so concurrent
	// invocations of different tools / resources / prompts never share or race
	// this map (the concurrent-reuse contract).
	ToolOAuthProviders map[string]auth.OAuthProvider

	// Injection, when non-nil, binds this connection to per-user credential
	// INJECTION for a receiver-style MCP server: on each identity-stamped
	// outbound tool call the driver SOURCES the acting principal's credential
	// from Injection.Provider (the same per-user broker-pull as OAuthProvider —
	// per-user via the ctx identity, fetched-not-held) and INJECTS it in the
	// declared form (a request header, an `Authorization: Basic` value, or a
	// `_meta` key). Mutually exclusive with OAuthProvider / ToolOAuthProviders /
	// a static `Authorization` header (one auth mode per connection). Resolved
	// once at construction; immutable thereafter — the per-user value is pulled
	// per-call from the ctx and never held here (the concurrent-reuse contract).
	Injection *CredentialInjection

	// ArtifactEgress, when non-empty, declares which parameters on which
	// of this server's tools carry artifact BYTES. When a mapped
	// parameter arrives carrying an artifact id, the driver resolves it
	// through the run-scoped resolver seated on the dispatch ctx and
	// writes the resolved bytes into the outbound tool-call body as
	// standard base64 — the model authored an id and never sees content.
	//
	// Set only when the operator declared the connection byte-eligible;
	// the boot validator, both control-plane persistence doors and
	// [Attach] each refuse a mapping without that declaration, so the
	// driver never has to re-derive the eligibility rule. Empty leaves
	// every outbound call byte-identical to a build without the feature.
	//
	// Read once at construction and captured BY VALUE into each tool's
	// invocation closure at Discover, so a live mapping change takes
	// effect at the next attach / reconcile and never mid-flight (the
	// concurrent-reuse contract).
	ArtifactEgress artifactegress.Mapping

	// ArtifactEgressMaxBytes bounds ONE substituted artifact value on one
	// outbound call. Resolved from the operator's
	// `tools.mcp_artifact_egress_max_bytes` (which carries a documented
	// default) before construction. A value above it is REFUSED loud,
	// never truncated. Ignored when ArtifactEgress is empty; when it is
	// not, a non-positive value fails the call rather than being read as
	// "unbounded".
	ArtifactEgressMaxBytes int
}

type ContentKind string

type ContentPart struct {
	Kind     ContentKind
	Image    *ImageRef
	Audio    *AudioRef
	Link     *LinkRef
	Embedded *EmbeddedRef
}

type CredentialInjection struct {
	// Provider is the resolved broker the per-user credential is pulled from.
	Provider auth.OAuthProvider
	// Form selects the injection form.
	Form InjectionForm
	// Header is the target request header name for InjectionFormHeader.
	Header string
	// BasicUsername is the (non-secret, optional) username half for
	// InjectionFormBasic; the pulled credential is the password half.
	BasicUsername string
	// MetaKey is the split target `_meta` key path for InjectionFormMeta.
	MetaKey []string
}

type Cursor struct {
	// NextPageToken is the cursor for the next page, or empty when the
	// page is the last.
	NextPageToken string
}

type DiscoveryResult struct {
	DiscoveryID   string
	ToolCount     int
	ResourceCount int
	PromptCount   int
}

type EmbeddedRef struct {
	URI      string
	MIMEType string
	Text     string
	Blob     []byte
}

type ExactRemovalFence struct {
	// contains filtered or unexported fields
}

type HealthBucket struct {
	StartMs   int64
	LatencyMs int64
}

type HealthSnapshot struct {
	HandshakeLatencyBuckets []HealthBucket
	ReconnectHistory        []ReconnectEntry
	TransportErrorRate      float64
}

type ImageRef struct {
	Data     []byte
	MIMEType string
}

type InjectionForm string

type LinkRef struct {
	URI         string
	Name        string
	Title       string
	Description string
	MIMEType    string
}

type ListFilter struct {
	// State filters to servers in any of the given states. Empty = all.
	State []ServerState
	// Transport filters to servers on any of the given transports.
	Transport []string
	// HasOAuth, when set, filters on OAuth-binding presence.
	HasOAuth *bool
	// HasRecentError, when set, filters on recent-error presence.
	HasRecentError *bool
	// NamePrefix filters to servers whose name has the prefix.
	NamePrefix string
	// PageToken is the opaque cursor from a prior page.
	PageToken string
	// PageSize is the requested max row count (clamped by the Registry).
	PageSize int
}

type MCPToolValue struct {
	// Text concatenates every TextContent block in encounter order.
	Text string
	// Parts is the ordered, typed slice of every non-text content
	// block. Empty when the response is pure text.
	Parts []ContentPart
	// StructuredContent is the MCP `structuredContent` field on
	// servers that support typed JSON output (mcpsdk.ToolHandlerFor).
	// nil when absent.
	StructuredContent any
	// AppRef is the MCP Apps reference for an invoked tool that declared
	// an interactive UI. The canonical `io.modelcontextprotocol/ui`
	// (ext-apps) dialect binds the `ui://` UI resource to the tool
	// DEFINITION (`_meta.ui.resourceUri` on the tool, captured at
	// discovery); a server MAY additionally place a per-result hint on the
	// CallToolResult `_meta.ui` slot. The value here is the reconciled
	// reference — the tool-definition binding, merged with any per-result
	// hint — set on the result by `Provider.callTool`. `lowerCallToolResult`
	// alone populates it only from the per-result `_meta`; the binding is
	// merged in by `callTool`, which holds the discovery-time binding. It is
	// nil for ordinary (non-app) tools. AppRef is excluded from the JSON
	// wire form (`json:"-"`) so it never reaches the LLM-facing observation —
	// it is a host-side projection consumed by the app-tool-call proxy and
	// the discovery event, not planner context.
	AppRef *AppRef `json:"-"`
	// ArtifactEgress records the artifact values the runtime resolved
	// into THIS call's outbound arguments — one content-free entry per
	// substituted parameter (artifact id, parameter name, byte count,
	// `sha256:` digest). Nil for a tool that maps no artifact parameters.
	//
	// Unlike AppRef above, it is deliberately INCLUDED in the JSON wire
	// form and therefore reaches the observation and the trajectory. The
	// contrast is the design: AppRef is a host-side projection the model
	// has no business reading, whereas the model AUTHORED the artifact
	// id, and telling it "the id you named was delivered, N bytes" is
	// honest, content-free and replayable. Without it a model could not
	// distinguish a delivered document from an ignored parameter.
	//
	// It carries no bytes, so it is safe everywhere the observation goes.
	ArtifactEgress []artifactegress.Record `json:"artifact_egress,omitempty"`
}

type MCPTransportMode string

type OAuthProviderResolver interface {
	// Get resolves a provider by bare name; the bool reports presence.
	Get(name string) (auth.OAuthProvider, bool)
	// Names returns every resolvable provider name, sorted, for a fail-loud
	// error message.
	Names() []string
}

type PreparationAuthRequiredError struct{ Challenge AuthChallenge }

type PreparedAttachment struct {
	// contains filtered or unexported fields
}

type ProbeResult struct {
	OK        bool
	LatencyMs int64
	Error     string
}

type PromptArgView struct {
	Name        string
	Description string
	Required    bool
}

type PromptView struct {
	Name        string
	Description string
	Arguments   []PromptArgView
}

type Provider struct {
	// contains filtered or unexported fields
}

type ReconnectEntry struct {
	OccurredAt time.Time
	Reason     string
}

type RegistrationSwap struct {
	// contains filtered or unexported fields
}

type Registry struct {
	// contains filtered or unexported fields
}

type RegistryOption func(*Registry)

type ResourceOffloadedPayload struct {
	events.SafeSealed
	// Identity scopes the offload to the (tenant, user, session) triple
	// the read ran under.
	Identity identity.Quadruple
	// ArtifactID is the content-addressed reference the heavy content
	// was stored under.
	ArtifactID string
	// Source identifies what was offloaded: the resource URI for a
	// `read_resource`, or the tool name for an app-tool-call result.
	Source string
	// SizeBytes is the length of the offloaded content.
	SizeBytes int64
	// OccurredAt is the wall-clock instant the offload happened.
	OccurredAt time.Time
}

type ResourceUpdatedPayload struct {
	events.SafeSealed
	Identity   identity.Quadruple
	Source     tools.ToolSourceID
	URI        string
	OccurredAt time.Time
}

type ResourceView struct {
	URI       string
	MimeType  string
	SizeBytes int64
	Name      string
	Title     string
}

type ScopeShortfall struct {
	// RequiredScopes is the parsed `scope` challenge parameter.
	RequiredScopes []string
	// GrantedScopes is the binding's most-recently-granted scope set
	// (populated by the reader that resolved the token, not the transport).
	GrantedScopes []string
	// DownstreamResource is the host the challenge came from.
	DownstreamResource string
	// Origin is the scheme://host[:port] the challenge was observed on.
	Origin string
	// WWWAuthenticate is the verbatim challenge header value.
	WWWAuthenticate string
	// ToolName is the server-side tool name the call targeted (populated by
	// the reader that owns the tool name, not the transport).
	ToolName string
	// CapturedAt is the wall-clock instant the shortfall was observed.
	CapturedAt time.Time
}

type ServerRegistration struct {
	// Provider is the live MCP provider. Required.
	Provider serverProvider
	// Transport is the wire transport string ("stdio" / "http+sse" /
	// "streamable-http" / "websocket"). Required.
	Transport string
	// URLOrCommand is the transport-prefixed endpoint or argv command.
	URLOrCommand string
	// Policy is the server's ToolPolicy. Zero-valued → DefaultPolicy.
	Policy tools.ToolPolicy
	// ContentShapes lists the canonical content shapes the tools return.
	ContentShapes []string
	// OAuthBindingCount is the configured OAuth binding count.
	OAuthBindingCount int
	// InitialState is the server's starting state. Zero-valued →
	// ServerStateOffline.
	InitialState ServerState
	// OAuthDiscoveryAllowedOrigins is the explicit per-connection cross-origin
	// allowance list for OAuth-requirement discovery fetches. Empty
	// leaves the authorization-server hop needs-allowance (partial discovery).
	OAuthDiscoveryAllowedOrigins []string
	// Owner is the (tenant, agent) reconcile-view tag for a RUNTIME-ADDED
	// server. Boot-declared servers leave it zero (untagged) — the
	// owner-scoped reconcile view never enumerates a zero-owner entry. The
	// runtime-add attach path stamps a non-zero owner (fail-closed there when
	// either component is missing); nothing about resolution or dispatch reads
	// it (those stay bare-name and process-global).
	Owner auth.Owner
	// DescriptorFingerprint is the canonical digest of the complete
	// NON-SECRET runtime-added descriptor. Empty for boot registrations.
	DescriptorFingerprint string
}

type ServerState string

type ServerView struct {
	// Name is the unique server / source id.
	Name string
	// Transport is the wire transport string.
	Transport string
	// URLOrCommand is the transport-prefixed endpoint or argv command.
	URLOrCommand string
	// State is the canonical state chip.
	State ServerState
	// LastDiscoveryAt is the last successful discovery instant (zero
	// when discovery has never run).
	LastDiscoveryAt time.Time
	// ToolCount / ResourceCount / PromptCount are the advertised counts.
	ToolCount     int
	ResourceCount int
	PromptCount   int
	// RecentLatencyMs is the most recent observed handshake / probe
	// latency.
	RecentLatencyMs int64
	// ErrorRatePerMin is the transport-error rate over the window.
	ErrorRatePerMin float64
	// OAuthBindingCount is the number of OAuth bindings configured.
	OAuthBindingCount int
	// RawHTMLTrusted reports the per-server raw-HTML trust flag.
	RawHTMLTrusted bool
	// DisplayModes lists the advertised MCP-Apps DisplayMode values.
	DisplayModes []string
	// ContentShapes lists the canonical content shapes the server's
	// tools return.
	ContentShapes []string
	// Policy is the read-only ToolPolicy projection.
	Policy tools.ToolPolicy
	// OAuthRequirement is the OAuth requirement advertised by the server and
	// discovered on demand — the verbatim RFC 9728 → RFC 8414 chain
	// plus provenance. Nil when no discovery has run. Populated only on the
	// DETAIL read (GetServer); the list projection leaves it nil so the hot
	// list row stays compact (§4.3-recorded — the requirement rides get/probe,
	// not list). It is inert, server-supplied, UNVERIFIED data.
	OAuthRequirement *auth.OAuthRequirement
	// LastScopeShortfall is the most recent downstream insufficient-scope
	// step-up (a `403` + `WWW-Authenticate` marking
	// `error="insufficient_scope"`) observed on this connection. Nil when
	// none seen. Populated only on the DETAIL read (GetServer), mirroring how
	// OAuthRequirement rides get — the list row stays compact. Inert,
	// server-supplied data; the operator acts on it, the runtime never does.
	LastScopeShortfall *ScopeShortfall
}

type ToolContextCapturer interface {
	Capture(ctx context.Context, in CapturedToolContext) error
}