mcp

type AuthIdentity struct {
	Hub              string   `json:"hub"`
	UserID           int64    `json:"user_id"`
	Username         string   `json:"username"`
	DisplayName      string   `json:"display_name,omitempty"`
	DefaultNamespace string   `json:"default_namespace"`
	Namespaces       []string `json:"namespaces"`
}

type FlightCatalogProvider interface {
	// FlightCatalog returns readable flights from one catalog projection.
	FlightCatalog(context.Context) ([]*tapper.Flight, error)
}

type FlightOrientationProvider interface {
	// Resolve reloads the pinned root's live graph and selects one flight for
	// the current call; an empty selection resolves to the root.
	Resolve(context.Context, string, string) (*Orientation, error)
}

type FlightProvider interface {
	// ListFlights returns the canonical refs of every flight this identity can see.
	ListFlights(context.Context) ([]string, error)
	// GetFlight resolves one flight by ref.
	GetFlight(context.Context, string) (*tapper.Flight, error)
	// CreateFlight persists a new flight and returns the stored manifest.
	CreateFlight(context.Context, tapper.CreateFlightOptions) (*tapper.Flight, error)
	// UpdateFlight applies a partial edit and returns the stored manifest. The
	// every subsequent authority-bearing call resolves the live graph again.
	UpdateFlight(context.Context, tapper.UpdateFlightOptions) (*tapper.Flight, error)
	// DeleteFlight removes a flight.
	DeleteFlight(context.Context, tapper.DeleteFlightOptions) error
}

type FlightSearchResult struct {
	Flights   []FlightSearchRow `json:"flights"`
	Truncated bool              `json:"truncated"`
}

type FlightSearchRow struct {
	Ref         string `json:"ref"`
	Title       string `json:"title"`
	Description string `json:"description"`
}

type IdentityProvider interface {
	// Identities returns the authenticated identities, without credentials.
	// Local MCP reports the selected Hub login; hosted MCP reports the one
	// authenticated account.
	Identities(context.Context) ([]AuthIdentity, error)
}

type KegDefaults struct {
	tapper.KegTargetOptions
	// contains filtered or unexported fields
}

type KegDeletionProvider interface {
	// DeleteKeg removes the explicit canonical KEG and all its data, including snapshots.
	DeleteKeg(context.Context, string) error
}

type KegDiscoveryProvider interface {
	// ListKegs returns every identity-authorized canonical keg ref. MCP applies
	// the call-selected flight cover before releasing results, so
	// implementations do not filter by flight themselves.
	ListKegs(context.Context) ([]string, error)
	// CreateKeg provisions a keg and returns its canonical @namespace/keg ref.
	// The MCP gate has already checked the flight's manage_kegs capability;
	// implementations apply their own transport's identity authorization, which
	// the capability never substitutes for.
	CreateKeg(context.Context, tapper.CreateKegOptions) (string, error)
}

type KegSearchProvider interface {
	// SearchKegs returns bounded identity-authorized metadata matches.
	SearchKegs(context.Context, string) (KegSearchResult, error)
}

type KegSearchResult struct {
	Kegs      []KegSearchRow `json:"kegs"`
	Warnings  []string       `json:"warnings"`
	Truncated bool           `json:"truncated"`
	Partial   bool           `json:"partial"`
}

type KegSearchRow struct {
	Ref         string `json:"ref"`
	Role        string `json:"role"`
	Title       string `json:"title"`
	Description string `json:"description"`
	Visibility  string `json:"visibility"`
	Source      string `json:"source"`
}

type Orientation struct {
	Root             *tapper.Flight
	Flight           *tapper.Flight
	Path             []string
	AvailableFlights []string
	Identity         string
	Revision         string
	// RootHub binds the proof to this connection's validating Hub.
	RootHub        string
	AllowedTargets []string
	Payload        string
	Kegs           []tapper.OrientationKeg
	// AggregateKegs is the pinned root plus every accessible transitive
	// descendant, merged by highest effective role. It exists only on a live
	// per-call candidate and is never published into shared session state.
	AggregateKegs []tapper.OrientationKeg
	Warnings      []string
	// FullAccess marks an ungoverned no-flight candidate. It uses the identity's
	// real KEG roles, publishes the complete tool inventory, and emits no Hub
	// orientation header.
	FullAccess            bool
	ReconnectInstructions string
}

type OrientationProvider interface {
	// Load selects the pinned root and renders it into a complete candidate.
	// It is the transport's reload boundary: whatever "which flight am I on"
	// depends on is re-read here and nowhere else.
	Load(context.Context) (*Orientation, error)
	// Render renders the exact supplied manifest. It must not consult a mutable
	// selection again, because its caller has already decided which flight is
	// authoritative and is only asking for the payload.
	Render(context.Context, *tapper.Flight) (*Orientation, error)
}

type PublicFlight struct {
	Name         string              `json:"name"`
	Hash         string              `json:"hash"`
	Title        string              `json:"title"`
	Description  string              `json:"description"`
	Source       string              `json:"source"`
	Visibility   string              `json:"visibility"`
	Capabilities []string            `json:"capabilities"`
	Cover        []PublicFlightCover `json:"cover"`
	Subflights   []string            `json:"subflights"`
	Instructions string              `json:"instructions"`
}

type PublicFlightCover struct {
	Namespace string `json:"namespace"`
	Keg       string `json:"keg"`
	Role      string `json:"role"`
	Depth     int    `json:"depth"`
}

type ServerOptions struct {
	// Logger is the structured logger for invocation logging. When nil,
	// invocation logging is silently skipped.
	Logger *slog.Logger
	// Reporter receives privacy-minimized tool invocation telemetry. It is
	// independent of Logger and may be nil.
	Reporter tapper.InvocationReporter
	// Providers replace transport-specific registration branches. Nil providers
	// use local adapters over tap; hosted callers inject authenticated catalog
	// and account implementations.
	OrientationProvider OrientationProvider
	FlightProvider      FlightProvider
	KegProvider         KegDiscoveryProvider
	KegSearchProvider   KegSearchProvider
	IdentityProvider    IdentityProvider
	// SharedFilesystem reports that this server and the agent host driving it
	// see the same filesystem. That holds for stdio (`tap mcp`), where a path in
	// a tool argument names the same file on both sides, and never for a hosted
	// endpoint, where it would name the server's own disk. It selects the
	// attachment transfer tools: see registerFileTools. The zero value is the
	// safe one, so a caller that forgets it gets the hosted surface.
	SharedFilesystem bool
}