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.
	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. Empty until the
	// invocation path stamps it; it is NOT parsed from the server's
	// `_meta` (a result never carries it).
	ToolCallID string
}

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
	// 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
}

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 connect-time
	// request (initialize / discovery) predates any per-call identity and so
	// carries only the static Headers — a documented limitation.
	OAuthProvider auth.OAuthProvider

	// MetaAnnotations is a static, non-secret set of operator-declared
	// key/values merged verbatim into the `_meta` map on every
	// identity-stamped per-call RPC, so a deployment can carry its own
	// attribution vocabulary to a shared server. Reserved keys (the triple
	// keys, `agent_id`, `traceparent`, `tracestate`, and any
	// `io.modelcontextprotocol/`-prefixed key) are rejected at config /
	// attach validation and can never shadow the triple or agent provenance
	// (those are stamped last). 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-tool OAuth-provider overrides keyed by the
	// MCP server-side tool name (mirroring ToolPolicies' shape). A tool named
	// here binds THAT provider for its CallTool RPCs only; an unlisted tool
	// 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). Scope is
	// CallTool ONLY — resource/prompt paths keep resolving OAuthProvider.
	// Read-only after New; the resolved provider is read per-call from the
	// call's own tool name, so concurrent invocations of different tools
	// never share or race this map (the concurrent-reuse contract).
	ToolOAuthProviders map[string]auth.OAuthProvider
}

type ContentKind string

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

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 HealthBucket struct {
	StartMs   int64
	LatencyMs int64
}

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

type ImageRef struct {
	Data     []byte
	MIMEType 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:"-"`
}

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

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
}