// Package pluginapi defines host-side plugin capability schemas and adapters.package pluginapi import (	"context"	"encoding/json"	"net/http"	"net/url"	"time") // Plugin is the host-side representation produced from a dynamic plugin registration.type Plugin struct {	// Metadata identifies the plugin binary and its published source.	Metadata Metadata	// Capabilities declares the optional integration points implemented by the plugin.	Capabilities Capabilities	// SchemaVersion is the plugin contract version negotiated at registration.	// Zero means unset (treated as legacy by the host).	SchemaVersion uint32} // Metadata describes a plugin for registry, logging, and diagnostics.type Metadata struct {	// Name is the stable human-readable plugin name.	Name string	// Version is the plugin release version.	Version string	// Author identifies the plugin author or organization.	Author string	// GitHubRepository is the repository URL for plugin source and support.	GitHubRepository string	// Logo is a plugin-provided display asset reference for management clients.	Logo string	// ConfigFields describes plugin-owned configuration fields for management clients.	ConfigFields []ConfigField} // ConfigFieldType classifies plugin-owned configuration values for management clients.type ConfigFieldType string const (	// ConfigFieldTypeString describes a string configuration value.	ConfigFieldTypeString ConfigFieldType = "string"	// ConfigFieldTypeNumber describes a numeric configuration value.	ConfigFieldTypeNumber ConfigFieldType = "number"	// ConfigFieldTypeInteger describes an integer configuration value.	ConfigFieldTypeInteger ConfigFieldType = "integer"	// ConfigFieldTypeBoolean describes a boolean configuration value.	ConfigFieldTypeBoolean ConfigFieldType = "boolean"	// ConfigFieldTypeEnum describes a string value constrained to EnumValues.	ConfigFieldTypeEnum ConfigFieldType = "enum"	// ConfigFieldTypeArray describes an array configuration value.	ConfigFieldTypeArray ConfigFieldType = "array"	// ConfigFieldTypeObject describes an object configuration value.	ConfigFieldTypeObject ConfigFieldType = "object") // ConfigField describes a plugin-owned configuration field for management clients.type ConfigField struct {	// Name is the configuration key under plugins.configs.<pluginID>.	Name string	// Type classifies the field value for management clients.	Type ConfigFieldType	// EnumValues lists allowed values when Type is ConfigFieldTypeEnum.	EnumValues []string	// Description explains how the plugin uses the field.	Description string} // Capabilities groups the optional host integration interfaces exposed by a plugin.type Capabilities struct {	// ModelRegistrar contributes development-time model metadata to the host registry.	ModelRegistrar ModelRegistrar	// ModelProvider contributes provider-native static and per-auth model metadata.	ModelProvider ModelProvider	// AuthProvider lets the host parse, login, poll, and refresh plugin provider auths.	AuthProvider AuthProvider	// FrontendAuthProvider authenticates frontend requests before proxy handling.	FrontendAuthProvider FrontendAuthProvider	// FrontendAuthProviderExclusive makes this frontend auth provider the only active request auth provider when selected.	FrontendAuthProviderExclusive bool	// Scheduler chooses an auth candidate before the built-in scheduler runs.	Scheduler Scheduler	// ModelRouter routes matching requests to a plugin executor, the router's own executor,	// or a built-in provider before model-to-provider resolution and auth selection.	ModelRouter ModelRouter	// Executor sends requests to an upstream provider or local backend.	Executor ProviderExecutor	// ExecutorModelScope declares whether Executor serves static models, OAuth auth models, or both.	// Empty defaults to ExecutorModelScopeBoth for backward compatibility.	ExecutorModelScope ExecutorModelScope	// ExecutorInputFormats lists request protocols accepted directly by Executor. Executors must declare at least one.	ExecutorInputFormats []string	// ExecutorOutputFormats lists response protocols emitted directly by Executor. Executors must declare at least one.	ExecutorOutputFormats []string	// RequestTranslator converts canonical requests into provider-specific payloads.	RequestTranslator RequestTranslator	// RequestNormalizer converts provider-specific requests into canonical payloads.	RequestNormalizer RequestNormalizer	// ResponseTranslator converts canonical responses into provider-specific payloads.	ResponseTranslator ResponseTranslator	// ResponseBeforeTranslator normalizes upstream responses before native translation.	ResponseBeforeTranslator ResponseNormalizer	// ResponseAfterTranslator normalizes translated responses before delivery.	ResponseAfterTranslator ResponseNormalizer	// RequestInterceptor rewrites execution requests before and after credential selection.	RequestInterceptor RequestInterceptor	// RequestLifecyclePlugin asynchronously receives one terminal event for each request that reached request interception.	RequestLifecyclePlugin RequestLifecyclePlugin	// ResponseInterceptor rewrites successful non-streaming HTTP execution responses before downstream delivery.	ResponseInterceptor ResponseInterceptor	// StreamChunkInterceptor rewrites successful HTTP stream chunks before downstream delivery.	StreamChunkInterceptor StreamChunkInterceptor	// WebSocketResponseObserver receives upstream WebSocket response events during execution.	WebSocketResponseObserver WebSocketResponseObserver	// ThinkingApplier applies validated thinking configuration to provider payloads.	ThinkingApplier ThinkingApplier	// UsagePlugin receives completed usage records.	UsagePlugin UsagePlugin	// CommandLinePlugin declares and handles plugin-owned command-line flags.	CommandLinePlugin CommandLinePlugin	// ManagementAPI declares plugin-owned diagnostic Management API and resource routes.	ManagementAPI ManagementAPI	// QuotaProvider surfaces credential quota and billing information for management clients.	QuotaProvider QuotaProvider} // ExecutorModelScope declares which model-registration paths a plugin executor supports.type ExecutorModelScope string const (	// ExecutorModelScopeBoth means the executor supports static and OAuth auth-bound models.	ExecutorModelScopeBoth ExecutorModelScope = "both"	// ExecutorModelScopeStatic means the executor supports only non-OAuth static models.	ExecutorModelScopeStatic ExecutorModelScope = "static"	// ExecutorModelScopeOAuth means the executor supports only OAuth auth-bound models.	ExecutorModelScopeOAuth ExecutorModelScope = "oauth") // ModelInfo describes a model contributed by a plugin.type ModelInfo struct {	// ID is the stable model identifier used in API requests.	ID string	// Object is the API object type, usually "model".	Object string	// Created is the Unix timestamp when the model metadata was created.	Created int64	// OwnedBy identifies the model owner or provider.	OwnedBy string	// Type classifies the model capability family.	Type string	// DisplayName is the user-facing model name.	DisplayName string	// Name is the provider-native model name.	Name string	// Version identifies the model revision when available.	Version string	// Description is a short user-facing model summary.	Description string	// InputTokenLimit is the maximum accepted input token count.	InputTokenLimit int64	// OutputTokenLimit is the maximum generated output token count.	OutputTokenLimit int64	// SupportedGenerationMethods lists supported generation method names.	SupportedGenerationMethods []string	// ContextLength is the maximum combined context length.	ContextLength int64	// MaxCompletionTokens is the maximum completion token count.	MaxCompletionTokens int64	// SupportedParameters lists request parameters supported by the model.	SupportedParameters []string	// SupportedInputModalities lists accepted input modality names.	SupportedInputModalities []string	// SupportedOutputModalities lists produced output modality names.	SupportedOutputModalities []string	// Thinking describes optional reasoning controls for the model.	Thinking *ThinkingSupport	// UserDefined reports whether the model was provided by user configuration.	UserDefined bool} // ThinkingSupport describes supported reasoning budget controls.type ThinkingSupport struct {	// Min is the minimum accepted reasoning budget.	Min int	// Max is the maximum accepted reasoning budget.	Max int	// ZeroAllowed reports whether disabling reasoning is supported.	ZeroAllowed bool	// DynamicAllowed reports whether automatic reasoning budget selection is supported.	DynamicAllowed bool	// Levels lists supported named reasoning levels.	Levels []string} // HostConfigSummary describes host configuration relevant to plugin providers.type HostConfigSummary struct {	// AuthDir is the resolved directory containing provider auth material.	AuthDir string	// ProxyURL is the configured upstream proxy URL.	ProxyURL string	// ForceModelPrefix reports whether model aliases should keep provider prefixes.	ForceModelPrefix bool	// OAuthModelAlias maps providers to configured model aliases.	OAuthModelAlias map[string][]ModelAlias	// ExcludedModels maps providers to model names hidden by host configuration.	ExcludedModels map[string][]string} // ModelAlias describes one configured provider model alias.type ModelAlias struct {	// Name is the provider model name.	Name string	// Alias is the host-facing model alias.	Alias string} // AuthData describes a plugin provider auth record exchanged with the host.type AuthData struct {	// Provider is the provider key associated with the auth.	Provider string	// ID is the stable host auth identifier.	ID string	// FileName is the source or persisted auth file name.	FileName string	// Label is the user-facing auth label.	Label string	// Prefix is the configured model prefix for this auth.	Prefix string	// ProxyURL is the auth-specific proxy URL when configured.	ProxyURL string	// Disabled reports whether the auth should be skipped.	Disabled bool	// StorageJSON contains provider-owned persisted auth data.	StorageJSON []byte	// Metadata contains mutable host-managed auth metadata.	Metadata map[string]any	// Attributes contains immutable routing and provider attributes.	Attributes map[string]string	// NextRefreshAfter is the earliest time the host should refresh this auth.	NextRefreshAfter time.Time} // AuthParseRequest describes auth material offered to a plugin parser.type AuthParseRequest struct {	// Provider is the provider key being parsed.	Provider string	// Path is the source path of the auth material when available.	Path string	// FileName is the auth file name.	FileName string	// RawJSON contains the raw auth file payload.	RawJSON []byte	// Host contains relevant host configuration.	Host HostConfigSummary} // AuthParseResponse returns the parser decision and parsed auth data.type AuthParseResponse struct {	// Handled reports whether the plugin recognized the auth material.	Handled bool	// Auth is the parsed auth record when Handled is true.	Auth AuthData	// Auths contains multiple parsed auth records when one auth material expands into several runtime auths.	Auths []AuthData} // AuthProvider parses, logs in, polls, and refreshes plugin provider auths.type AuthProvider interface {	Identifier() string	ParseAuth(context.Context, AuthParseRequest) (AuthParseResponse, error)	StartLogin(context.Context, AuthLoginStartRequest) (AuthLoginStartResponse, error)	PollLogin(context.Context, AuthLoginPollRequest) (AuthLoginPollResponse, error)	RefreshAuth(context.Context, AuthRefreshRequest) (AuthRefreshResponse, error)} // AuthLoginStartRequest asks a plugin to start a provider login flow.type AuthLoginStartRequest struct {	// Provider is the provider key for the login flow.	Provider string	// BaseURL is the host callback or login base URL.	BaseURL string	// Host contains relevant host configuration.	Host HostConfigSummary	// HTTPClient executes upstream HTTP requests through host transport policy.	HTTPClient HostHTTPClient `json:"-"`	// Metadata carries plugin-defined login context.	Metadata map[string]any} // AuthLoginStartResponse returns login flow state for polling.type AuthLoginStartResponse struct {	// Provider is the provider key for the login flow.	Provider string	// URL is the user-facing login URL.	URL string	// State is the opaque plugin login state used for polling.	State string	// ExpiresAt is the time when this login flow expires.	ExpiresAt time.Time	// Metadata carries plugin-defined polling context.	Metadata map[string]any} // AuthLoginPollRequest asks a plugin to poll a provider login flow.type AuthLoginPollRequest struct {	// Provider is the provider key for the login flow.	Provider string	// State is the opaque plugin login state returned by StartLogin.	State string	// Host contains relevant host configuration.	Host HostConfigSummary	// HTTPClient executes upstream HTTP requests through host transport policy.	HTTPClient HostHTTPClient `json:"-"`	// Metadata carries plugin-defined polling context.	Metadata map[string]any} // AuthLoginStatus describes the current provider login state.type AuthLoginStatus string const (	// AuthLoginStatusPending means the login flow is still waiting.	AuthLoginStatusPending AuthLoginStatus = "pending"	// AuthLoginStatusSuccess means the login flow produced auth data.	AuthLoginStatusSuccess AuthLoginStatus = "success"	// AuthLoginStatusError means the login flow failed.	AuthLoginStatusError AuthLoginStatus = "error") // AuthLoginPollResponse returns the login poll status and auth data.type AuthLoginPollResponse struct {	// Status is the current login flow state.	Status AuthLoginStatus	// Message contains provider-facing login progress or error text.	Message string	// Auth is the completed auth record when Status is success.	Auth AuthData	// Auths contains multiple completed auth records when one login flow expands into several runtime auths.	Auths []AuthData} // AuthRefreshRequest asks a plugin to refresh provider auth data.type AuthRefreshRequest struct {	// AuthID identifies the auth record to refresh.	AuthID string	// AuthProvider identifies the credential provider.	AuthProvider string	// StorageJSON contains provider-owned persisted auth data.	StorageJSON []byte	// Metadata contains mutable host-managed auth metadata.	Metadata map[string]any	// Attributes contains immutable routing and provider attributes.	Attributes map[string]string	// Host contains relevant host configuration.	Host HostConfigSummary	// HTTPClient executes upstream HTTP requests through host transport policy.	HTTPClient HostHTTPClient `json:"-"`} // AuthRefreshResponse returns refreshed provider auth data.type AuthRefreshResponse struct {	// Auth is the refreshed auth record.	Auth AuthData	// NextRefreshAfter is the earliest time the host should refresh again.	NextRefreshAfter time.Time} // ModelRegistrar registers plugin-provided models with the host.type ModelRegistrar interface {	RegisterModels(context.Context, ModelRegistrationRequest) (ModelRegistrationResponse, error)} // ModelRegistrationRequest carries host context for model registration.type ModelRegistrationRequest struct {	// Plugin is the metadata of the plugin being registered.	Plugin Metadata} // ModelRegistrationResponse returns provider and model metadata to register.type ModelRegistrationResponse struct {	// Provider is the provider key associated with the returned models.	Provider string	// Models is the complete set of plugin-provided models.	Models []ModelInfo} // ModelProvider contributes provider-native static and per-auth model metadata.type ModelProvider interface {	StaticModels(context.Context, StaticModelRequest) (ModelResponse, error)	ModelsForAuth(context.Context, AuthModelRequest) (ModelResponse, error)} // StaticModelRequest carries host context for provider static models.type StaticModelRequest struct {	// Plugin is the metadata of the plugin being registered.	Plugin Metadata	// Host contains relevant host configuration.	Host HostConfigSummary} // AuthModelRequest carries auth context for provider model discovery.type AuthModelRequest struct {	// Plugin is the metadata of the plugin being registered.	Plugin Metadata	// AuthID identifies the auth record used for discovery.	AuthID string	// AuthProvider identifies the credential provider.	AuthProvider string	// StorageJSON contains provider-owned persisted auth data.	StorageJSON []byte	// Metadata contains mutable host-managed auth metadata.	Metadata map[string]any	// Attributes contains immutable routing and provider attributes.	Attributes map[string]string	// Host contains relevant host configuration.	Host HostConfigSummary	// HTTPClient executes upstream HTTP requests through host transport policy.	HTTPClient HostHTTPClient `json:"-"`} // ModelResponse returns provider and model metadata discovered by a plugin.type ModelResponse struct {	// Provider is the provider key associated with the returned models.	Provider string	// Models is the complete set of discovered provider models.	Models []ModelInfo	// AuthUpdate contains updated auth data from model discovery when needed.	AuthUpdate AuthData} // FrontendAuthProvider authenticates frontend requests before proxy routing.type FrontendAuthProvider interface {	Identifier() string	Authenticate(context.Context, FrontendAuthRequest) (FrontendAuthResponse, error)} // FrontendAuthRequest describes an inbound frontend authentication request.type FrontendAuthRequest struct {	// Method is the HTTP method.	Method string	// Path is the request path.	Path string	// Headers contains inbound request headers.	Headers http.Header	// Query contains inbound query parameters.	Query url.Values	// Body contains the raw request body.	Body []byte} // FrontendAuthResponse reports the authentication decision and identity metadata.type FrontendAuthResponse struct {	// Authenticated reports whether the request was accepted.	Authenticated bool	// Principal is the authenticated subject identifier.	Principal string	// Metadata carries plugin-defined identity attributes for downstream use.	Metadata map[string]string} const (	// SchedulerBuiltinRoundRobin delegates auth selection to the built-in round-robin scheduler.	SchedulerBuiltinRoundRobin = "round-robin"	// SchedulerBuiltinFillFirst delegates auth selection to the built-in fill-first scheduler.	SchedulerBuiltinFillFirst = "fill-first") // Scheduler chooses an auth candidate before the built-in scheduler runs.type Scheduler interface {	Pick(context.Context, SchedulerPickRequest) (SchedulerPickResponse, error)} // ModelRouter routes matching requests to a plugin executor, the router's own executor,// or a built-in provider before model-to-provider resolution and auth selection.type ModelRouter interface {	RouteModel(context.Context, ModelRouteRequest) (ModelRouteResponse, error)} // SchedulerPickRequest describes the routing context offered to a scheduler plugin.type SchedulerPickRequest struct {	// Plugin is the metadata of the plugin being executed.	Plugin Metadata	// Provider is the primary provider key requested by the route.	Provider string	// Providers contains every provider key accepted by the route.	Providers []string	// Model is the requested model identifier.	Model string	// Stream reports whether the request expects streaming output.	Stream bool	// Options contains request-scoped scheduler inputs.	Options SchedulerOptions	// Candidates contains auth records available for selection.	Candidates []SchedulerAuthCandidate} // SchedulerOptions carries request-scoped scheduler inputs.type SchedulerOptions struct {

Lines 1–500 of 1669. Load more