plugin_sdk

type AgentMessageChunk = pb.AgentMessageChunk

type AgentMessageRequest = pb.AgentMessageRequest

type AgentPlugin interface {
	Plugin

	// HandleAgentMessage processes a user message and streams responses back.
	// req contains: user message, available LLMs/tools/datasources, conversation history
	// stream is used to send back content chunks, tool calls, thinking, errors, etc.
	// The agent should call stream.Send() for each chunk and end with a DONE chunk.
	HandleAgentMessage(req *pb.AgentMessageRequest, stream grpc.ServerStreamingServer[pb.AgentMessageChunk]) error

	// GetManifest returns the plugin manifest as JSON bytes.
	// The manifest declares permissions, scopes, and metadata.
	GetManifest() ([]byte, error)
}

type AnalyticsRequest = pb.AnalyticsRequest

type App = pb.App

type AuditRecord struct {
	ID           uint32
	Timestamp    time.Time
	UserID       uint32
	UserEmail    string
	UserName     string
	Action       string
	Method       string
	Route        string
	Status       int
	ResourceType string
	ResourceID   string
	ResourceName string
	DiffJSON     string // {"field": {"old":..,"new":..}}, sensitive columns redacted
	Error        string
}

type AuthHandler interface {
	Plugin
	HandleAuth(ctx Context, req *pb.AuthRequest) (*pb.AuthResponse, error)

	// GetAppByCredential retrieves app information during authentication.
	// This is called by the auth system to validate app credentials.
	GetAppByCredential(ctx Context, credential string) (*pb.App, error)

	// GetUserByCredential retrieves user information during authentication.
	// This is called by the auth system to validate user credentials.
	GetUserByCredential(ctx Context, credential string) (*pb.User, error)
}

type AuthRequest = pb.AuthRequest

type AuthResponse = pb.AuthResponse

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

type BudgetUsageRequest = pb.BudgetUsageRequest

type ConfigProvider interface {
	Plugin

	// GetConfigSchema returns the JSON Schema for plugin configuration.
	// The schema should follow jsonschema.org format.
	GetConfigSchema() ([]byte, error)
}

type Context struct {
	// Runtime indicates whether this is Studio or Gateway
	Runtime RuntimeType

	// RequestID uniquely identifies this request (if applicable)
	RequestID string

	// AppID is the application making the request (if known)
	AppID uint32

	// UserID is the user making the request (if known)
	UserID uint32

	// LLMID is the LLM being accessed (if applicable)
	LLMID uint32

	// LLMSlug is the LLM slug/identifier (if applicable)
	LLMSlug string

	// Vendor is the LLM vendor (e.g., "anthropic", "openai")
	Vendor string

	// EdgeID is the edge instance identifier (only set in RuntimeGateway)
	// Empty string in RuntimeStudio context
	EdgeID string

	// EdgeNamespace is the edge namespace (only set in RuntimeGateway)
	// Empty string in RuntimeStudio context
	EdgeNamespace string

	// Metadata provides additional context as key-value pairs
	Metadata map[string]string

	// TraceContext provides distributed tracing context
	TraceContext map[string]string

	// Services provides access to host services (KV storage, logging, app management)
	Services ServiceBroker

	// Internal context for cancellation and timeouts
	context.Context
}

type CustomEndpointHandler interface {
	Plugin

	// GetEndpointRegistrations declares which HTTP endpoints this plugin serves.
	// Called after Initialize() and again on plugin reload.
	GetEndpointRegistrations() ([]*pb.EndpointRegistration, error)

	// HandleEndpointRequest handles a non-streaming HTTP request.
	// Returns a complete HTTP response (status, headers, body).
	HandleEndpointRequest(ctx Context, req *pb.EndpointRequest) (*pb.EndpointResponse, error)

	// HandleEndpointRequestStream handles a streaming HTTP request (SSE, MCP Streamable HTTP).
	// Plugin sends EndpointResponseChunks: first HEADERS, then BODY chunks, finally DONE.
	// The gateway flushes each BODY chunk to the HTTP client immediately.
	// Plugins that only serve non-streaming endpoints can return an Unimplemented error.
	HandleEndpointRequestStream(ctx Context, req *pb.EndpointRequest, stream grpc.ServerStreamingServer[pb.EndpointResponseChunk]) error
}

type DataCollectionResponse = pb.DataCollectionResponse

type DataCollector interface {
	Plugin

	// HandleProxyLog processes raw proxy request/response logs.
	HandleProxyLog(ctx Context, req *pb.ProxyLogRequest) (*pb.DataCollectionResponse, error)

	// HandleAnalytics processes token usage and cost analytics.
	HandleAnalytics(ctx Context, req *pb.AnalyticsRequest) (*pb.DataCollectionResponse, error)

	// HandleBudgetUsage processes budget consumption data.
	HandleBudgetUsage(ctx Context, req *pb.BudgetUsageRequest) (*pb.DataCollectionResponse, error)
}

type Direction int

type EdgePayload struct {
	Payload           []byte            // Arbitrary payload data from edge plugin
	EdgeID            string            // Edge instance that sent the payload
	EdgeNamespace     string            // Namespace of the edge instance
	CorrelationID     string            // Optional correlation ID for tracking
	Metadata          map[string]string // Optional key-value metadata
	EdgeTimestamp     int64             // Unix timestamp when generated at edge
	ReceivedTimestamp int64             // Unix timestamp when received at control
}

type EdgePayloadReceiver interface {
	Plugin

	// AcceptEdgePayload is called when a payload arrives from an edge instance.
	// payload contains the raw data sent by the edge plugin via SendToControl().
	// edgeID identifies which edge instance sent the payload.
	// correlationID can be used for request/response matching or tracking.
	// metadata contains any additional key-value data from the edge plugin.
	//
	// Returns:
	//   - handled: true if this plugin processed the payload
	//   - error: non-nil if processing failed
	AcceptEdgePayload(ctx Context, payload *EdgePayload) (handled bool, err error)
}

type EndpointRegistration = pb.EndpointRegistration

type EndpointRequest = pb.EndpointRequest

type EndpointResponse = pb.EndpointResponse

type EndpointResponseChunk = pb.EndpointResponseChunk

type EnrichedRequest = pb.EnrichedRequest

type Event struct {
	// ID is a UUID for deduplication and tracing
	ID string

	// Topic is the logical topic name (e.g., "config.update", "metrics.report")
	Topic string

	// Origin is the node/plugin ID that created the event
	Origin string

	// Dir is the direction (informational - when received, always treated as local)
	Dir Direction

	// Payload is the application-specific data as JSON
	Payload json.RawMessage
}

type EventHandler func(event Event)

type EventService interface {
	// Publish sends an event to the event bus.
	// topic: logical topic name (e.g., "cache.hit", "config.reload")
	// payload: arbitrary data (will be JSON-encoded)
	// dir: routing direction:
	//   - DirLocal: stays on local bus only
	//   - DirUp: forwarded from edge to control
	//   - DirDown: forwarded from control to edge(s)
	Publish(ctx context.Context, topic string, payload interface{}, dir Direction) error

	// PublishRaw sends an event with a pre-encoded JSON payload.
	PublishRaw(ctx context.Context, topic string, payload []byte, dir Direction) error

	// Subscribe registers a handler for events on a specific topic.
	// Returns a subscription ID that can be used to unsubscribe.
	// The handler is called asynchronously for each matching event.
	Subscribe(topic string, handler EventHandler) (string, error)

	// SubscribeAll registers a handler for all events regardless of topic.
	// Returns a subscription ID that can be used to unsubscribe.
	SubscribeAll(handler EventHandler) (string, error)

	// Unsubscribe removes a subscription by ID.
	// After this call, the handler will no longer receive events.
	Unsubscribe(subscriptionID string) error
}

type GatewayServices interface {
	// GetApp retrieves app details from local Gateway database
	// Returns microgateway_management.GetAppResponse proto type
	GetApp(ctx context.Context, appID uint32) (interface{}, error)

	// ListApps lists apps from local Gateway database
	ListApps(ctx context.Context, page, limit int32, isActive *bool) (interface{}, error)

	// GetLLM retrieves LLM details from local Gateway database
	GetLLM(ctx context.Context, llmID uint32) (interface{}, error)

	// ListLLMs lists LLMs from local Gateway database
	ListLLMs(ctx context.Context, page, limit int32, vendor string, isActive *bool) (interface{}, error)

	// GetBudgetStatus retrieves budget status (Gateway-only feature)
	GetBudgetStatus(ctx context.Context, appID uint32, llmID *uint32) (interface{}, error)

	// GetModelPrice retrieves model pricing from local Gateway database
	GetModelPrice(ctx context.Context, modelName, vendor string) (interface{}, error)

	// ListModelPrices lists model prices from local Gateway database
	ListModelPrices(ctx context.Context, vendor string) (interface{}, error)

	// ValidateCredential validates an API credential (Gateway-only feature)
	ValidateCredential(ctx context.Context, secret string) (interface{}, error)

	// StoreApp writes an App from the control plane into the local gateway database.
	// Used by auth plugins that need to provision apps dynamically without waiting
	// for periodic config sync. Uses upsert semantics (creates if not exists, updates if exists).
	// The request should contain the full app configuration including resource associations.
	// Requires "apps.write" scope in the plugin manifest.
	StoreApp(ctx context.Context, appID uint32, name, description string, isActive bool,
		userID uint32, metadata string, namespace string,
		llmIDs, toolIDs, datasourceIDs []uint32) error

	// SendToControl queues a payload to be sent to the AI Studio control plane
	// This is used by plugins running on edge (microgateway) instances to send
	// data back to the control plane for aggregation or processing.
	// Returns the number of payloads pending in the queue.
	SendToControl(ctx context.Context, payload []byte, correlationID string, metadata map[string]string) (int64, error)

	// SendToControlJSON is a convenience method that JSON-encodes a value and sends it to control
	SendToControlJSON(ctx context.Context, value interface{}, correlationID string, metadata map[string]string) (int64, error)
}

type GroupSummary struct {
	ID        uint32
	Name      string
	IsDefault bool
}

type HeadersRequest = pb.HeadersRequest

type HeadersResponse = pb.HeadersResponse

type HookType string

type KVService interface {
	// Read retrieves a value by key
	// Returns error if key doesn't exist or has expired
	Read(ctx context.Context, key string) ([]byte, error)

	// Write stores a value with the given key and optional expiration
	// expireAt is optional - pass nil for no expiration
	// Returns whether a new key was created (true) or existing updated (false)
	Write(ctx context.Context, key string, value []byte, expireAt *time.Time) (bool, error)

	// WriteWithTTL stores a value with a TTL (time-to-live)
	// Expiration is calculated as time.Now().Add(ttl)
	// Returns whether a new key was created (true) or existing updated (false)
	WriteWithTTL(ctx context.Context, key string, value []byte, ttl time.Duration) (bool, error)

	// Delete removes a key
	// Returns whether the key existed and was deleted
	Delete(ctx context.Context, key string) (bool, error)

	// List returns all keys with the given prefix
	// Returns empty slice if no keys match
	List(ctx context.Context, prefix string) ([]string, error)
}

type LicenseInfo struct {
	// Valid indicates whether a valid enterprise license is present
	Valid bool

	// DaysRemaining is the number of days until license expires (-1 for community/never expires)
	DaysRemaining int

	// Type is the license type: "community" or "enterprise"
	Type string

	// Entitlements is a list of enabled features/entitlements
	Entitlements []string

	// Organization is the licensed organization name (enterprise only)
	Organization string

	// ExpiresAt is the license expiration timestamp (zero for community licenses)
	ExpiresAt time.Time
}

type ListAppsOptions struct {
	IsActive  *bool
	Namespace string
	UserID    *uint32
}

type LogService interface {
	Debug(msg string, fields ...interface{})
	Info(msg string, fields ...interface{})
	Warn(msg string, fields ...interface{})
	Error(msg string, fields ...interface{})
}

type MCPServerSummary struct {
	ID             uint32
	Name           string
	Slug           string
	Description    string
	Kind           string
	PrivacyScore   *int // nil until an administrator sets it
	IsActive       bool
	DashboardState string
	Brokerable     bool
	Tags           []string
	UpdatedAt      time.Time
}

type ManifestProvider interface {
	Plugin

	// GetManifest returns the plugin manifest as JSON bytes.
	// The manifest declares hooks, permissions, and metadata.
	GetManifest() ([]byte, error)
}

type MetadataAuditEntry struct {
	ID            uint32
	Action        string // set | merge | delete
	UserID        uint32
	Source        string // "user", "plugin:<id>", "system", ...
	BeforeJSON    string
	AfterJSON     string
	HooksExecuted []string
	CreatedAt     time.Time
}

type Notification struct {
	// ID is an optional dedupe key. The platform scopes it to the plugin, so two
	// calls with the same ID produce a single notification per recipient.
	ID string
	// Type is a free-form label stored on the notification (e.g. "access_request").
	Type string
	// Title is required (max 255 characters).
	Title string
	// Content is the body, rendered as markdown in the admin UI (max 10000 characters).
	Content string
	// NotifyAdmins delivers the notification to every admin with notifications enabled.
	NotifyAdmins bool
	// UserID delivers the notification to a specific user (0 = none).
	UserID uint32
	// Link is what the notification opens when clicked: a same-origin path
	// ("/admin/...", "/portal/...") or an http(s) URL. Optional.
	Link string
	// Links gives each audience its own target and overrides Link: "admin"
	// for the admin fan-out, "portal" for the user named by UserID.
	Links map[string]string
}

type ObjectHookHandler interface {
	Plugin

	// GetObjectHookRegistrations declares which object operations this plugin wants to handle.
	// Returns a list of registrations specifying object types, hook types, and execution priority.
	GetObjectHookRegistrations() ([]*pb.ObjectHookRegistration, error)

	// HandleObjectHook processes a single object hook invocation.
	// req contains: hook type, object type, object data (JSON), user ID, operation ID
	// Returns: allow/reject decision, optional modified object, plugin metadata
	HandleObjectHook(ctx Context, req *pb.ObjectHookRequest) (*pb.ObjectHookResponse, error)
}

type PermissionAction string

type PermissionResource struct {
	// Key is kebab-case and unique within the plugin; the platform registers
	// it as "plugin:<manifest id>:<key>".
	Key         string
	Label       string
	Description string
	// Actions offered, read first (e.g. read, write, delete, publish).
	Actions []PermissionAction
	// Sensitive withholds read from read-only system roles.
	Sensitive bool
}

type Plugin interface {
	// GetInfo returns metadata about the plugin
	GetInfo() PluginInfo

	// Initialize is called when plugin starts.
	// config contains runtime-specific configuration from the host.
	// The Context parameter provides runtime information (Studio vs Gateway)
	// and access to host services (KV storage, logging, etc.).
	Initialize(ctx Context, config map[string]string) error

	// Shutdown is called before plugin stops.
	// Plugins should clean up resources and complete in-flight operations.
	Shutdown(ctx Context) error
}

type PluginContext = pb.PluginContext

type PluginInfo struct {
	Name        string // Plugin name (e.g., "llm-rate-limiter")
	Version     string // Semantic version (e.g., "1.0.0")
	Description string // Human-readable description
}

type PluginRequest = pb.PluginRequest

type PluginResponse = pb.PluginResponse

type PortalUIProvider interface {
	Plugin

	// HandlePortalRPC processes RPC calls from the portal (end-user) UI.
	// This is SEPARATE from HandleRPC which only handles admin UI calls.
	// method: The RPC method name (e.g., "submit_feedback", "get_user_data")
	// payload: JSON payload as bytes from the portal frontend
	// userCtx: Authenticated portal user context (never nil)
	// Returns: JSON response as bytes
	HandlePortalRPC(method string, payload []byte, userCtx *PortalUserContext) ([]byte, error)
}

type PortalUserContext struct {
	UserID   uint32
	Email    string
	Name     string
	IsAdmin  bool
	Groups   []string
	Metadata map[string]string
	// Permissions is the caller's effective permission set as
	// "resource:action" strings; ["*"] means full administrator. Empty for
	// portal users with no administrative role.
	Permissions []string
}

type PostAuthHandler interface {
	Plugin
	HandlePostAuth(ctx Context, req *pb.EnrichedRequest) (*pb.PluginResponse, error)
}

type PreAuthHandler interface {
	Plugin
	HandlePreAuth(ctx Context, req *pb.PluginRequest) (*pb.PluginResponse, error)
}

type ProxyLogRequest = pb.ProxyLogRequest

type ResolvedMetadataSchema struct {
	// FieldsJSON is a JSON array of field definitions:
	// {key,label,description,type,required,severity,vocabulary_slug,pattern,min,max,
	//  max_length,warn_if_past,portal_visible,gateway_visible,order}.
	FieldsJSON string
	// JSONSchema is a draft-07 JSON Schema for the values object (vocabularies as enums).
	JSONSchema string
	// VocabulariesJSON maps vocabulary slug → [{value,label,description,deprecated}]
	// for every vocabulary referenced by FieldsJSON.
	VocabulariesJSON string
	// Enforcement is MetadataEnforcementAdvisory or MetadataEnforcementEnforce.
	Enforcement string
	// SchemaSlugs lists the schemas that contributed fields.
	SchemaSlugs []string
}

type ResourceFormComponent struct {
	// Tag is the custom element tag name (e.g., "mcp-server-selector").
	Tag string

	// EntryPoint is the path to the JS file relative to plugin assets
	// (e.g., "ui/webc/mcp-selector.js").
	EntryPoint string
}

type ResourceInstance struct {
	// ID is the plugin-assigned unique identifier for this instance.
	// Stored as a string to accommodate any ID format.
	ID string

	// Name is the human-readable display name.
	Name string

	// Description is an optional description.
	Description string

	// PrivacyScore is the privacy score (0-100). Only meaningful
	// if the ResourceTypeRegistration has HasPrivacyScore=true.
	PrivacyScore int

	// Metadata is arbitrary plugin-defined metadata as JSON bytes.
	// This is opaque to the platform but included in config snapshots.
	//
	// SECURITY: Do NOT store secrets, credentials, or PII in this field.
	// Metadata is propagated to all gateways, cached in the join table,
	// and may appear in logs or be accessible to other plugins.
	Metadata []byte

	// IsActive indicates if this instance is currently usable.
	IsActive bool

	// AccessGrantedViaApp optionally overrides the resource type's
	// AccessGrantedViaApp for this one instance. Nil inherits the type value.
	AccessGrantedViaApp *bool
}

type ResourceProvider interface {
	Plugin

	// GetResourceTypeRegistrations declares the resource types this plugin provides.
	// Called once after Initialize() and again on plugin reload.
	GetResourceTypeRegistrations() ([]*ResourceTypeRegistration, error)

	// ListResourceInstances returns all instances of a given resource type.
	// The platform calls this to populate selection UI in the App form.
	ListResourceInstances(ctx Context, resourceTypeSlug string) ([]*ResourceInstance, error)

	// GetResourceInstance retrieves a single resource instance by its ID.
	GetResourceInstance(ctx Context, resourceTypeSlug string, instanceID string) (*ResourceInstance, error)

	// ValidateResourceSelection is called during app create/update to let the plugin
	// validate the selected resource instances. Returns nil if valid, or an error
	// describing why the selection is invalid.
	ValidateResourceSelection(ctx Context, resourceTypeSlug string, instanceIDs []string, appID uint32) error

	// CreateResourceInstance creates a new instance from a submission approval.
	// payload is a JSON-encoded creation payload defined by the plugin.
	CreateResourceInstance(ctx Context, resourceTypeSlug string, payload []byte) (*ResourceInstance, error)
}

type ResourceTypeRegistration struct {
	// Slug is the machine-readable identifier (e.g., "mcp_servers").
	// Must be unique per plugin. Used in API paths and DB storage.
	Slug string

	// Name is the human-readable display name (e.g., "MCP Servers").
	Name string

	// Description explains what this resource type is.
	Description string

	// Icon is an optional icon identifier (Material icon name or asset path).
	Icon string

	// HasPrivacyScore indicates whether instances carry a privacy score.
	// If true, instances' privacy scores are subject to the generalized
	// privacy rule: no resource score may exceed the max LLM score in the app.
	HasPrivacyScore bool

	// SupportsSubmissions indicates whether community users can submit
	// new instances of this resource type through the submission workflow.
	SupportsSubmissions bool

	// SupportsMetadata indicates whether instances of this resource type can
	// carry governed metadata (Enterprise). When true, admins can attach
	// schema-validated metadata to instances under the object type
	// "plugin_resource:<plugin_id>:<slug>". Must also be set as
	// "supports_metadata" on the resource type in manifest.json.
	SupportsMetadata bool

	// FormComponent declares how the plugin provides its App Form UI section.
	// If nil, the platform renders a standard multi-select populated via ListResourceInstances.
	FormComponent *ResourceFormComponent

	// SubmissionSchema is an optional JSON Schema (with "type": "object")
	// describing the payload of community submissions for this type. When set,
	// the portal renders the submission form from it and the platform validates
	// submitted payloads against it before accepting them. Only meaningful when
	// SupportsSubmissions is true.
	SubmissionSchema string

	// AccessGrantedViaApp declares that an App credential is what grants
	// access to instances of this type (for example servers proxied by the
	// gateway, whose handler checks the App's plugin resource bindings).
	// Only such types are offered in the App forms, show "Build app" in the
	// portal catalog and travel in the gateway config snapshot. Types whose
	// instances are informational, or gated by the plugin's own access
	// request flow, should set this to false.
	//
	// When nil the platform applies its default: true when the plugin also
	// declares the custom_endpoint hook, false otherwise.
	AccessGrantedViaApp *bool

	// PortalDetailPath is an optional path template to an instance's page in
	// the portal. When access is not granted through an App the unified
	// catalog opens it as the item's detail view, in place of the built-in
	// detail page; otherwise the built-in page links to it. "{id}" is
	// replaced with the URL-escaped instance ID, e.g.
	// "/portal/plugins/asset-catalog#/assets/{id}". Must be a same-origin
	// path starting with "/"; portal plugin routes match the pathname
	// exactly, so carry the ID in the hash of a registered portal route.
	PortalDetailPath string

	// DefaultAccess decides whether active instances are granted to the
	// Default team (which every user joins). DefaultAccessAuto (or empty,
	// the default) grants them, so every user sees them. DefaultAccessExplicit
	// leaves access to team grants: an administrator's on the Teams page, or
	// the plugin's own through StudioServices.SetResourceInstanceGroups. Use
	// it for instances that are an internal record until someone decides to
	// share them. Community Edition has no team segmentation and always
	// behaves as DefaultAccessAuto.
	DefaultAccess string
}

type ResponseHandler interface {
	Plugin

	// OnBeforeWriteHeaders is called before response headers are sent to the client.
	// Use this to modify or add response headers.
	OnBeforeWriteHeaders(ctx Context, req *pb.HeadersRequest) (*pb.HeadersResponse, error)

	// OnBeforeWrite is called before response body is sent to the client.
	// This is called for both regular responses and streaming chunks.
	OnBeforeWrite(ctx Context, req *pb.ResponseWriteRequest) (*pb.ResponseWriteResponse, error)
}

type ResponseWriteRequest = pb.ResponseWriteRequest

type ResponseWriteResponse = pb.ResponseWriteResponse

type RouterSummary struct {
	ID             uint32
	Kind           string // "model_router" | "semantic_router"
	Name           string
	Slug           string
	Namespace      string
	Description    string
	Active         bool
	LLMIDs         []uint32
	ModelRouterIDs []uint32 // semantic routers only: targets that are model routers
	UpdatedAt      time.Time
}

type RuntimeType string

type Schedule struct {
	ID             string                 // Unique identifier from manifest
	Name           string                 // Human-readable name
	Cron           string                 // Cron expression (e.g., "0 * * * *")
	Timezone       string                 // Timezone for cron evaluation (e.g., "America/New_York", "UTC")
	Enabled        bool                   // Whether schedule is currently enabled
	TimeoutSeconds int                    // Maximum execution time in seconds
	Config         map[string]interface{} // Schedule-specific configuration from manifest
}

type SchedulerPlugin interface {
	Plugin

	// ExecuteScheduledTask is called when a scheduled task needs to run.
	// ctx provides access to services (KV, logging) but has no request context.
	// schedule contains the schedule definition including ID, name, cron expression, and custom config.
	// Returns error if execution failed (will be recorded in execution history).
	ExecuteScheduledTask(ctx Context, schedule *Schedule) error
}

type ServiceBroker interface {
	// KV returns the key-value storage service (works in both contexts)
	KV() KVService

	// Logger returns the logging service (works in both contexts)
	Logger() LogService

	// Gateway returns Gateway-specific services (only available in RuntimeGateway)
	// Returns nil if called in Studio context
	Gateway() GatewayServices

	// Studio returns Studio-specific services (only available in RuntimeStudio)
	// Returns nil if called in Gateway context
	Studio() StudioServices

	// Events returns the event pub/sub service (works in both contexts)
	// Allows plugins to publish and subscribe to events that flow across
	// edge/control boundaries via the event bridge system.
	Events() EventService
}

type SessionAware interface {
	// OnSessionReady is called when a session is first established.
	// This is the place to set up event subscriptions, start background goroutines,
	// or initialize resources that require a live broker connection.
	// This is only called once per plugin lifetime (on the first OpenSession),
	// not on session renewals (subsequent OpenSession calls after timeout).
	OnSessionReady(ctx Context)

	// OnSessionClosing is called before a session is explicitly closed.
	// This is NOT called on session timeout (timeouts expect the host to re-open).
	// Use this to clean up resources before the plugin shuts down.
	OnSessionClosing(ctx Context)
}

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

type StreamCompleteHandler interface {
	Plugin

	// OnStreamComplete is called after a streaming response has finished.
	// The accumulated_response contains all SSE chunks concatenated together.
	// This can be used to cache the complete response for future requests.
	OnStreamComplete(ctx Context, req *pb.StreamCompleteRequest) (*pb.StreamCompleteResponse, error)
}

type StudioServices interface {
	// GetApp retrieves app details from AI Studio database
	// Returns ai_studio_management.GetAppResponse proto type
	GetApp(ctx context.Context, appID uint32) (interface{}, error)

	// ListApps lists apps from AI Studio database
	ListApps(ctx context.Context, page, limit int32) (interface{}, error)

	// UpdateAppWithMetadata updates app configuration including metadata
	UpdateAppWithMetadata(ctx context.Context, appID uint32, name, description string, isActive bool, llmIDs, toolIDs, datasourceIDs []uint32, monthlyBudget *float64, metadata string) (interface{}, error)

	// PatchAppMetadata atomically updates a single metadata key on an app.
	// To set a key: PatchAppMetadata(ctx, appID, "mykey", `"myvalue"`, false)
	// To delete a key: PatchAppMetadata(ctx, appID, "mykey", "", true)
	// Returns the full metadata JSON string after the operation.
	PatchAppMetadata(ctx context.Context, appID uint32, key, value string, deleteKey bool) (string, error)

	// ListAppsWithFilters lists apps with optional filtering by user_id, namespace, and is_active
	ListAppsWithFilters(ctx context.Context, page, limit int32, opts *ListAppsOptions) (interface{}, error)

	// GetLLM retrieves LLM details from AI Studio database
	GetLLM(ctx context.Context, llmID uint32) (interface{}, error)

	// ListLLMs lists LLMs from AI Studio database
	ListLLMs(ctx context.Context, page, limit int32) (interface{}, error)

	// ListTools lists tools (Studio-only feature)
	ListTools(ctx context.Context, page, limit int32) (interface{}, error)

	// CallLLM proxies LLM requests (for agent plugins, Studio-only)
	CallLLM(ctx context.Context, llmID uint32, model string, messages interface{}, temperature float64, maxTokens int32) (interface{}, error)

	// UpdatePluginConfig updates the plugin's own configuration in the database
	// configJSON should be a valid JSON string containing the full configuration
	// Returns success status and any error message
	UpdatePluginConfig(ctx context.Context, pluginID uint32, configJSON string) (bool, string, error)

	// UpdateLLMPlugins updates plugin associations for an LLM
	// If append is true, the plugin is added to existing associations; otherwise replaces all
	// Returns success status and the final list of plugin IDs
	UpdateLLMPlugins(ctx context.Context, llmID uint32, pluginIDs []uint32, append bool) (bool, string, []uint32, error)

	// CreateNotification raises an in-app notification (and email when SMTP is
	// configured) for all admins and/or a specific user.
	// Requires the "notifications.write" service scope.
	CreateNotification(ctx context.Context, n Notification) error

	// RegisterResourceTypes (re)registers the plugin's resource types at runtime.
	// When deactivateMissing is true, previously registered types absent from
	// regs are deactivated. Returns the number of types registered and deactivated.
	// Requires the "resource-types.manage" service scope.
	RegisterResourceTypes(ctx context.Context, regs []ResourceTypeRegistration, deactivateMissing bool) (registered uint32, deactivated uint32, err error)

	// RegisterPermissionResources (re)registers the plugin's runtime RBAC
	// resources: rows in the role editor beneath the plugin's own entry, keyed
	// "plugin:<manifest id>:<key>". Use it for resources only known at runtime
	// (asset classes an administrator defines); static ones belong in the
	// manifest's "rbac.resources". With removeMissing, runtime resources absent
	// from specs are removed (manifest-declared ones never are). Returns the
	// counts and the plugin's permission key. Requires the "rbac.register"
	// service scope.
	RegisterPermissionResources(ctx context.Context, specs []PermissionResource, removeMissing bool) (registered uint32, removed uint32, pluginKey string, err error)

	// GetObjectMetadata returns the stored governed metadata values as JSON and whether a record exists.
	// Requires the metadata.read scope.
	GetObjectMetadata(ctx context.Context, objectType, objectID string) (valuesJSON string, found bool, err error)

	// GetObjectMetadataForAudience narrows the stored values to one audience
	// (MetadataVisibilityPortal or MetadataVisibilityGateway). For the portal it also
	// returns displayJSON: [{key,label,type,value}] with vocabulary labels and user
	// names resolved, i.e. exactly what the built-in portal shows end users.
	// Requires the metadata.read scope.
	GetObjectMetadataForAudience(ctx context.Context, objectType, objectID, visibility string) (valuesJSON string, displayJSON string, found bool, err error)

	// SetObjectMetadata validates and stores governed metadata. merge=true keeps existing keys.
	// Returns the stored values and the validation result as JSON. When an enforcing schema
	// rejects the values, err is nil and ok is false; inspect validationResultJSON for details.
	// Requires the metadata.write scope.
	SetObjectMetadata(ctx context.Context, objectType, objectID, valuesJSON string, merge bool) (ok bool, storedValuesJSON string, validationResultJSON string, err error)

	// DeleteObjectMetadata removes the governed metadata of an object. Call it when the
	// plugin deletes the resource instance so no orphaned record remains. Absent records succeed.
	// Requires the metadata.write scope.
	DeleteObjectMetadata(ctx context.Context, objectType, objectID string) error

	// GetResolvedMetadataSchema returns the merged schema for an object type: field
	// definitions, the draft-07 JSON Schema, the vocabularies those fields use and the
	// enforcement level. Enough to render the form in the plugin's own UI.
	// Requires the metadata.read scope.
	GetResolvedMetadataSchema(ctx context.Context, objectType string) (*ResolvedMetadataSchema, error)

	// ValidateObjectMetadataForPublish validates the values an object will
	// hold once it goes live (stored record for objectID merged with
	// valuesJSON; "" objectID = being created): fields marked "required to
	// publish" are required and the result is always enforced. Call it before
	// moving a resource instance into a live/approved state.
	ValidateObjectMetadataForPublish(ctx context.Context, objectType, objectID, valuesJSON string) (valid bool, resultJSON string, err error)

	// ValidateObjectMetadata validates values without storing them.
	// Requires the metadata.read scope.
	ValidateObjectMetadata(ctx context.Context, objectType, valuesJSON string) (valid bool, enforced bool, resultJSON string, err error)

	// ListObjectMetadataAudit returns the governed metadata history of an
	// object, newest first (limit 0 = 100, capped at 500). Community Edition
	// returns an empty list. Requires the metadata.read scope.
	ListObjectMetadataAudit(ctx context.Context, objectType, objectID string, limit int) ([]MetadataAuditEntry, error)

	// ListAuditRecords returns the platform audit records for one resource
	// ("llm", "tool", "datasource", "mcp_server", "model_router",
	// "semantic_router", "app"), newest first, without request or response
	// bodies; mutationsOnly drops reads. Enterprise only: Community Edition
	// answers codes.Unimplemented. Requires the audit.read scope.
	ListAuditRecords(ctx context.Context, resourceType, resourceID string, limit int, mutationsOnly bool) ([]AuditRecord, error)

	// ListMCPServers / GetMCPServer read MCP servers without upstream URLs,
	// auth details or definitions. Requires the mcp-servers.read scope.
	ListMCPServers(ctx context.Context, page, limit int32) ([]MCPServerSummary, int64, error)
	GetMCPServer(ctx context.Context, serverID uint32) (*MCPServerSummary, error)

	// ListModelRouters, GetModelRouter, ListSemanticRouters and
	// GetSemanticRouter read routers with the LLMs (and, for semantic
	// routers, the model routers) they can send requests to. Enterprise
	// only. Requires the routers.read scope.
	ListModelRouters(ctx context.Context, page, limit int32) ([]RouterSummary, int64, error)
	GetModelRouter(ctx context.Context, routerID uint32) (*RouterSummary, error)
	ListSemanticRouters(ctx context.Context, page, limit int32) ([]RouterSummary, int64, error)
	GetSemanticRouter(ctx context.Context, routerID uint32) (*RouterSummary, error)

	// ListGroups lists every team, with the Default team flagged.
	ListGroups(ctx context.Context) ([]GroupSummary, error)
	// GetResourceInstanceGroups returns the IDs of the teams granted an instance.
	GetResourceInstanceGroups(ctx context.Context, resourceTypeSlug, instanceID string) ([]uint32, error)
	// SetResourceInstanceGroups adds groupIDs to an instance's grants, or with
	// replace sets them to exactly groupIDs. Returns the grants afterwards.
	SetResourceInstanceGroups(ctx context.Context, resourceTypeSlug, instanceID string, groupIDs []uint32, replace bool) ([]uint32, error)
	// ListAccessibleResourceInstances returns which instances of a type a user
	// can reach: seeAll when the user manages teams, otherwise the instance
	// IDs granted to the user's teams.
	ListAccessibleResourceInstances(ctx context.Context, resourceTypeSlug string, userID uint32) (seeAll bool, instanceIDs []string, err error)

	// SetAppGovernanceState suspends or reactivates an App (isActive nil
	// leaves it alone) and raises or clears governance flags on it (an empty
	// value clears a flag); the change is audited with the reason. It cannot
	// change what the App may access. Returns whether anything changed.
	// Requires the apps.lifecycle scope.
	SetAppGovernanceState(ctx context.Context, appID uint32, isActive *bool, flags map[string]string, reason string) (changed bool, err error)
}

type SubmissionEnvelope struct {
	Source               string                 `json:"source"` // always "submission"
	SubmissionID         uint32                 `json:"submission_id"`
	Submitter            SubmissionUser         `json:"submitter"`
	Reviewer             SubmissionUser         `json:"reviewer"`
	FinalPrivacyScore    int                    `json:"final_privacy_score"`
	SuggestedPrivacy     int                    `json:"suggested_privacy"`
	PrivacyJustification string                 `json:"privacy_justification"`
	AssignedCatalogues   []uint32               `json:"assigned_catalogues"`
	DocumentationURL     string                 `json:"documentation_url"`
	Notes                string                 `json:"notes"`
	Attestations         interface{}            `json:"attestations"`
	ResourcePayload      map[string]interface{} `json:"resource_payload"`
}

type SubmissionUser struct {
	ID    uint32 `json:"id"`
	Email string `json:"email"`
	Name  string `json:"name"`
}

type UIProvider interface {
	Plugin

	// GetAsset serves a static asset file (JS, CSS, images, etc.).
	// assetPath is relative to the plugin's asset root (e.g., "ui/webc/dashboard.js").
	// Returns: (content []byte, mimeType string, error)
	GetAsset(assetPath string) ([]byte, string, error)

	// ListAssets returns a list of all available assets.
	// pathPrefix can be used to filter assets (e.g., "ui/").
	ListAssets(pathPrefix string) ([]*pb.AssetInfo, error)

	// GetManifest returns the plugin manifest as JSON bytes.
	// The manifest declares UI components, permissions, and metadata.
	GetManifest() ([]byte, error)

	// HandleRPC processes custom RPC method calls from the UI.
	// method: The RPC method name (e.g., "get_statistics", "update_settings")
	// payload: JSON payload as bytes from the frontend
	// Returns: JSON response as bytes
	HandleRPC(method string, payload []byte) ([]byte, error)
}

type User = pb.User

type UserAwareRPCHandler interface {
	UIProvider

	// HandleRPCWithUser processes an admin RPC call with the caller's identity.
	HandleRPCWithUser(method string, payload []byte, userCtx *PortalUserContext) ([]byte, error)
}