pluginapi

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
}

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
}

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
}

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
}

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
}

type AuthLoginStatus string

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:"-"`
}

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
}

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
}

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

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:"-"`
}

type AuthRefreshResponse struct {
	// Auth is the refreshed auth record.
	Auth AuthData
	// NextRefreshAfter is the earliest time the host should refresh again.
	NextRefreshAfter time.Time
}

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
	// ResponseInterceptor rewrites successful non-streaming HTTP execution responses before downstream delivery.
	ResponseInterceptor ResponseInterceptor
	// StreamChunkInterceptor rewrites successful HTTP stream chunks before downstream delivery.
	StreamChunkInterceptor StreamChunkInterceptor
	// 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
}

type CommandLineExecutionRequest struct {
	// Plugin is the metadata of the plugin being executed.
	Plugin Metadata
	// Program is os.Args[0].
	Program string
	// Args contains every command-line argument after Program, including all flags.
	Args []string
	// ConfigPath is the effective configuration path used by the host.
	ConfigPath string
	// Host contains relevant host configuration.
	Host HostConfigSummary
	// Flags contains all currently registered command-line flags visible to the host.
	Flags map[string]CommandLineFlagValue
	// TriggeredFlags contains the plugin-owned flags that triggered this execution.
	TriggeredFlags map[string]CommandLineFlagValue
}

type CommandLineExecutionResponse struct {
	// Stdout is written to process stdout after plugin execution.
	Stdout []byte
	// Stderr is written to process stderr after plugin execution.
	Stderr []byte
	// Auths contains auth records created by the command. The host persists them.
	Auths []AuthData
	// ExitCode is used as the process exit code when non-zero.
	ExitCode int
}

type CommandLineFlag struct {
	// Name is the flag name without leading dashes.
	Name string
	// Usage is shown in -help output.
	Usage string
	// Type is one of bool, string, int, int64, float64, or duration.
	Type string
	// DefaultValue is parsed according to Type before flag registration.
	DefaultValue string
}

type CommandLineFlagValue struct {
	// Name is the flag name without leading dashes.
	Name string
	// Type is one of bool, string, int, int64, float64, or duration.
	Type string
	// Value is the parsed value in string form.
	Value string
	// Set reports whether the user explicitly provided this flag.
	Set bool
}

type CommandLinePlugin interface {
	RegisterCommandLine(context.Context, CommandLineRegistrationRequest) (CommandLineRegistrationResponse, error)
	ExecuteCommandLine(context.Context, CommandLineExecutionRequest) (CommandLineExecutionResponse, error)
}

type CommandLineRegistrationRequest struct {
	// Plugin is the metadata of the plugin being registered.
	Plugin Metadata
}

type CommandLineRegistrationResponse struct {
	// Flags contains the concrete flags to expose in -help.
	Flags []CommandLineFlag
}

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
}

type ConfigFieldType string

type ExecutorHTTPRequest struct {
	// AuthID identifies the selected credential.
	AuthID string
	// AuthProvider identifies the credential provider.
	AuthProvider string
	// Method is the HTTP method.
	Method string
	// URL is the absolute upstream URL.
	URL string
	// Headers contains request headers.
	Headers http.Header
	// Body contains the raw request body.
	Body []byte
	// StorageJSON contains provider-owned auth storage for this concrete auth.
	StorageJSON []byte
	// Metadata contains mutable host-managed auth metadata.
	Metadata map[string]any
	// Attributes contains immutable routing and provider attributes.
	Attributes map[string]string
	// HTTPClient executes upstream HTTP requests through host transport policy and request-log capture.
	HTTPClient HostHTTPClient `json:"-"`
}

type ExecutorHTTPResponse struct {
	// StatusCode is the upstream HTTP status code.
	StatusCode int
	// Headers contains upstream response headers.
	Headers http.Header
	// Body contains the raw response body.
	Body []byte
}

type ExecutorModelScope string

type ExecutorRequest struct {
	// AuthID identifies the selected credential.
	AuthID string
	// AuthProvider identifies the credential provider.
	AuthProvider string
	// Model is the requested model identifier.
	Model string
	// Format is the target request or response protocol format.
	Format string
	// Stream reports whether the request expects streaming output.
	Stream bool
	// Alt carries an alternate route or mode suffix when present.
	Alt string
	// Headers contains request headers passed to the executor.
	Headers http.Header
	// Query contains request query parameters passed to the executor.
	Query url.Values
	// OriginalRequest contains the raw client request body.
	OriginalRequest []byte
	// SourceFormat is the original client protocol format.
	SourceFormat string
	// Payload contains the translated provider payload.
	Payload []byte
	// Metadata is an extension bag for host and plugin coordination data.
	Metadata map[string]any
	// StorageJSON contains provider-owned auth storage for this concrete auth.
	StorageJSON []byte
	// AuthMetadata contains mutable host-managed auth metadata.
	AuthMetadata map[string]any
	// AuthAttributes contains immutable routing and provider attributes.
	AuthAttributes map[string]string
	// HTTPClient executes upstream HTTP requests through host transport policy and request-log capture.
	HTTPClient HostHTTPClient `json:"-"`
}

type ExecutorResponse struct {
	// Payload contains the raw response body.
	Payload []byte
	// Headers contains response headers to forward or inspect.
	Headers http.Header
	// Metadata is an extension bag for executor-specific response data.
	Metadata map[string]any
}

type ExecutorStreamChunk struct {
	// Payload contains the raw stream chunk bytes.
	Payload []byte
	// Err reports a stream error associated with this chunk.
	Err error
}

type ExecutorStreamResponse struct {
	// Headers contains response headers available before stream chunks.
	Headers http.Header
	// Chunks yields streaming payload chunks until the channel closes.
	Chunks <-chan ExecutorStreamChunk
}

type FrontendAuthProvider interface {
	Identifier() string
	Authenticate(context.Context, FrontendAuthRequest) (FrontendAuthResponse, error)
}

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
}

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
}

type HTTPRequest struct {
	// Method is the HTTP method.
	Method string
	// URL is the absolute upstream URL.
	URL string
	// Headers contains request headers.
	Headers http.Header
	// Body contains the raw request body.
	Body []byte
}

type HTTPResponse struct {
	// StatusCode is the upstream HTTP status code.
	StatusCode int
	// Headers contains upstream response headers.
	Headers http.Header
	// Body contains the raw response body.
	Body []byte
}

type HTTPStreamChunk struct {
	// Payload contains the raw stream chunk bytes.
	Payload []byte
	// Err reports a stream error associated with this chunk.
	Err error
}

type HTTPStreamResponse struct {
	// StatusCode is the upstream HTTP status code.
	StatusCode int
	// Headers contains upstream response headers.
	Headers http.Header
	// Chunks yields streaming payload chunks until the channel closes.
	Chunks <-chan HTTPStreamChunk
}

type HostAuthFileEntry struct {
	// ID identifies the credential record.
	ID string `json:"id,omitempty"`
	// AuthIndex is the stable runtime credential index.
	AuthIndex string `json:"auth_index,omitempty"`
	// Name is the credential file name or runtime identifier.
	Name string `json:"name"`
	// Type is the credential provider type.
	Type string `json:"type,omitempty"`
	// Provider is the credential provider key.
	Provider string `json:"provider,omitempty"`
	// Label is the human-readable credential label.
	Label string `json:"label,omitempty"`
	// Status is the current credential status.
	Status string `json:"status,omitempty"`
	// StatusMessage carries the latest status detail.
	StatusMessage string `json:"status_message,omitempty"`
	// Disabled reports whether the credential is disabled.
	Disabled bool `json:"disabled,omitempty"`
	// Unavailable reports whether the credential is currently unavailable.
	Unavailable bool `json:"unavailable,omitempty"`
	// RuntimeOnly reports whether the credential has no backing auth file.
	RuntimeOnly bool `json:"runtime_only,omitempty"`
	// Source reports whether the credential came from file or memory.
	Source string `json:"source,omitempty"`
	// Path is the backing auth file path when available.
	Path string `json:"path,omitempty"`
	// Size is the backing auth file size when available.
	Size int64 `json:"size,omitempty"`
	// ModTime is the last modification time when available.
	ModTime time.Time `json:"modtime,omitempty"`
	// UpdatedAt is the last credential update time.
	UpdatedAt time.Time `json:"updated_at,omitempty"`
	// CreatedAt is the credential creation time.
	CreatedAt time.Time `json:"created_at,omitempty"`
	// LastRefresh is the last refresh timestamp.
	LastRefresh time.Time `json:"last_refresh,omitempty"`
	// NextRetryAfter is the next retry timestamp.
	NextRetryAfter time.Time `json:"next_retry_after,omitempty"`
	// Email is the credential email when available.
	Email string `json:"email,omitempty"`
	// ProjectID is the credential project identifier when available.
	ProjectID string `json:"project_id,omitempty"`
	// AccountType is the credential account type when available.
	AccountType string `json:"account_type,omitempty"`
	// Account is the credential account identifier when available.
	Account string `json:"account,omitempty"`
	// Priority is the credential routing priority when available.
	Priority int `json:"priority,omitempty"`
	// Note is the credential note when available.
	Note string `json:"note,omitempty"`
	// Websockets reports whether websocket mode is enabled when available.
	Websockets bool `json:"websockets,omitempty"`
	// Success is the recent success count.
	Success int64 `json:"success,omitempty"`
	// Failed is the recent failure count.
	Failed int64 `json:"failed,omitempty"`
	// RecentRequests is the recent request snapshot.
	RecentRequests []HostRecentRequestEntry `json:"recent_requests,omitempty"`
}

type HostAuthGetRequest struct {
	// AuthIndex identifies the credential index.
	AuthIndex string `json:"auth_index"`
}

type HostAuthGetResponse struct {
	// AuthIndex identifies the credential index.
	AuthIndex string `json:"auth_index"`
	// Name is the credential file name or runtime identifier.
	Name string `json:"name,omitempty"`
	// Path is the backing auth file path when available.
	Path string `json:"path,omitempty"`
	// JSON contains the credential JSON payload.
	JSON json.RawMessage `json:"json"`
}

type HostAuthGetRuntimeResponse struct {
	// Auth is the runtime credential entry.
	Auth HostAuthFileEntry `json:"auth"`
}

type HostAuthSaveRequest struct {
	// Name is the target auth file name. It must end with .json.
	Name string `json:"name"`
	// JSON contains the credential JSON payload to save.
	JSON json.RawMessage `json:"json"`
}

type HostAuthSaveResponse struct {
	// Name is the saved auth file name.
	Name string `json:"name"`
	// Path is the saved auth file path.
	Path string `json:"path"`
}

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
}

type HostHTTPClient interface {
	Do(context.Context, HTTPRequest) (HTTPResponse, error)
	DoStream(context.Context, HTTPRequest) (HTTPStreamResponse, error)
}

type HostModelExecutionRequest struct {
	// EntryProtocol is the inbound client protocol format.
	EntryProtocol string `json:"entry_protocol"`
	// ExitProtocol is the target provider protocol format.
	ExitProtocol string `json:"exit_protocol"`
	// Model is the requested model identifier.
	Model string `json:"model"`
	// Stream reports whether the request expects streaming output.
	Stream bool `json:"stream"`
	// Body contains the raw request body.
	Body []byte `json:"body"`
	// Headers contains request headers.
	Headers http.Header `json:"headers"`
	// Query contains request query parameters.
	Query url.Values `json:"query"`
	// Alt carries an alternate route or mode suffix when present.
	Alt string `json:"alt"`
}

type HostModelExecutionResponse struct {
	// StatusCode is the model execution HTTP status code.
	StatusCode int `json:"status_code"`
	// Headers contains response headers.
	Headers http.Header `json:"headers"`
	// Body contains the raw response body.
	Body []byte `json:"body"`
}

type HostModelStreamCloseRequest struct {
	// StreamID identifies the host-owned stream.
	StreamID string `json:"stream_id"`
}

type HostModelStreamReadRequest struct {
	// StreamID identifies the host-owned stream.
	StreamID string `json:"stream_id"`
}

type HostModelStreamReadResponse struct {
	// Payload contains the raw stream chunk bytes.
	Payload []byte `json:"payload"`
	// Error reports a stream error associated with this read.
	Error string `json:"error"`
	// Done reports whether the stream has ended.
	Done bool `json:"done"`
}

type HostModelStreamResponse struct {
	// StatusCode is the model execution HTTP status code.
	StatusCode int `json:"status_code"`
	// Headers contains response headers.
	Headers http.Header `json:"headers"`
	// StreamID identifies the host-owned stream for later reads.
	StreamID string `json:"stream_id"`
}

type HostRecentRequestEntry struct {
	// Time is the recent request bucket label.
	Time string `json:"time"`
	// Success is the success count in the bucket.
	Success int64 `json:"success"`
	// Failed is the failure count in the bucket.
	Failed int64 `json:"failed"`
}

type ManagementAPI interface {
	RegisterManagement(context.Context, ManagementRegistrationRequest) (ManagementRegistrationResponse, error)
}

type ManagementHandler interface {
	HandleManagement(context.Context, ManagementRequest) (ManagementResponse, error)
}

type ManagementRegistrationRequest struct {
	// Plugin is the metadata of the plugin being registered.
	Plugin Metadata
	// BasePath is the only Management API prefix plugins may register under.
	BasePath string
	// ResourceBasePath is the plugin resource prefix for browser-navigable resources.
	ResourceBasePath string
}

type ManagementRegistrationResponse struct {
	// Routes contains the exact Management API routes to expose.
	Routes []ManagementRoute
	// Resources contains browser-navigable plugin resources exposed under /v0/resource/plugins/<pluginID>/.
	Resources []ResourceRoute
}

type ManagementRequest struct {
	// Method is the HTTP method.
	Method string
	// Path is the request path.
	Path string
	// Headers contains request headers.
	Headers http.Header
	// Query contains request query parameters.
	Query url.Values
	// Body contains the raw request body.
	Body []byte
}

type ManagementResponse struct {
	// StatusCode is the HTTP status code. Zero defaults to 200.
	StatusCode int
	// Headers contains response headers.
	Headers http.Header
	// Body contains the raw response body.
	Body []byte
}

type ManagementRoute struct {
	// Method is the HTTP method, for example GET or POST.
	Method string
	// Path is an exact path under /v0/management/. Relative paths are resolved under that prefix.
	Path string
	// Menu is a legacy resource menu label. GET routes with Menu are registered under /v0/resource/plugins/<pluginID>/.
	Menu string
	// Description explains the legacy resource menu entry for UI display.
	Description string
	// Handler processes matching Management API requests.
	Handler ManagementHandler
}

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
}

type ModelAlias struct {
	// Name is the provider model name.
	Name string
	// Alias is the host-facing model alias.
	Alias string
}

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
}

type ModelProvider interface {
	StaticModels(context.Context, StaticModelRequest) (ModelResponse, error)
	ModelsForAuth(context.Context, AuthModelRequest) (ModelResponse, error)
}

type ModelRegistrar interface {
	RegisterModels(context.Context, ModelRegistrationRequest) (ModelRegistrationResponse, error)
}

type ModelRegistrationRequest struct {
	// Plugin is the metadata of the plugin being registered.
	Plugin Metadata
}

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
}

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
}

type ModelRouteRequest struct {
	// Plugin is the metadata of the plugin being executed.
	Plugin Metadata
	// PluginID is the host-local plugin identifier for the router being executed.
	PluginID string
	// SourceFormat is the original client protocol format.
	SourceFormat string
	// RequestedModel is the client-requested model before provider/auth selection.
	RequestedModel string
	// Stream reports whether the request expects streaming output.
	Stream bool
	// Headers contains inbound request headers.
	Headers http.Header
	// Query contains inbound query parameters.
	Query url.Values
	// Body contains the raw client request payload.
	Body []byte
	// Metadata is a best-effort cloned context snapshot. Treat it as read-only and JSON-like.
	Metadata map[string]any
	// AvailableProviders lists built-in provider keys that currently have auth registered.
	// A router may target one of them via TargetKind=provider to run the request through the
	// built-in auth/executor path. Treat as read-only.
	AvailableProviders []string
}

type ModelRouteResponse struct {
	// Handled reports whether the plugin made a routing decision.
	Handled bool
	// TargetKind selects the execution target when Handled is true.
	TargetKind ModelRouteTargetKind
	// Target is the plugin executor id for executor routes and the provider key for provider routes.
	Target string
	// TargetModel is the model name used on the provider path. When empty, the host keeps
	// the original client-requested model. Only meaningful with TargetKind=provider.
	TargetModel string
	// Reason is an optional diagnostic reason for the route decision.
	Reason string
}

type ModelRouteTargetKind string

type ModelRouter interface {
	RouteModel(context.Context, ModelRouteRequest) (ModelRouteResponse, error)
}

type PayloadResponse struct {
	// Body contains the transformed payload bytes.
	Body []byte
}

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
}

type ProviderExecutor interface {
	Identifier() string
	Execute(context.Context, ExecutorRequest) (ExecutorResponse, error)
	ExecuteStream(context.Context, ExecutorRequest) (ExecutorStreamResponse, error)
	CountTokens(context.Context, ExecutorRequest) (ExecutorResponse, error)
	HttpRequest(context.Context, ExecutorHTTPRequest) (ExecutorHTTPResponse, error)
}

type RequestInterceptRequest struct {
	// SourceFormat is the original client protocol format.
	SourceFormat string
	// ToFormat is the selected upstream protocol format. It is empty before credential selection.
	ToFormat string
	// Model is the current execution model. After credential selection this is the selected upstream model.
	Model string
	// RequestedModel is the client-requested model before alias/model-pool rewriting.
	RequestedModel string
	// Stream reports whether the request expects streaming output.
	Stream bool
	// Headers contains the current upstream request headers.
	Headers http.Header
	// Body contains the current request payload.
	Body []byte
	// Metadata is a best-effort cloned context snapshot. Treat it as read-only and JSON-like.
	Metadata map[string]any
}

type RequestInterceptResponse struct {
	// Headers replaces matching current request headers and preserves headers not mentioned here.
	Headers http.Header
	// Body replaces the current request body only when non-empty.
	Body []byte
	// ClearHeaders explicitly removes current request headers before Headers is applied.
	ClearHeaders []string
}

type RequestInterceptor interface {
	InterceptRequestBeforeAuth(context.Context, RequestInterceptRequest) (RequestInterceptResponse, error)
	InterceptRequestAfterAuth(context.Context, RequestInterceptRequest) (RequestInterceptResponse, error)
}

type RequestNormalizer interface {
	NormalizeRequest(context.Context, RequestTransformRequest) (PayloadResponse, error)
}

type RequestTransformRequest struct {
	// FromFormat is the source protocol format.
	FromFormat string
	// ToFormat is the target protocol format.
	ToFormat string
	// Model is the requested model identifier.
	Model string
	// Stream reports whether the request expects streaming output.
	Stream bool
	// Body contains the payload to transform.
	Body []byte
}

type RequestTranslator interface {
	TranslateRequest(context.Context, RequestTransformRequest) (PayloadResponse, error)
}

type ResourceRoute struct {
	// Path is an exact path under /v0/resource/plugins/<pluginID>/. Relative paths are resolved under that prefix.
	Path string
	// Menu is the management UI menu label for this GET resource.
	Menu string
	// Description explains the resource route for UI display.
	Description string
	// Handler processes matching resource requests. Resource requests are not management-authenticated.
	Handler ManagementHandler
}

type ResponseInterceptRequest struct {
	SourceFormat    string
	Model           string
	RequestedModel  string
	Stream          bool
	RequestHeaders  http.Header
	ResponseHeaders http.Header
	OriginalRequest []byte
	RequestBody     []byte
	Body            []byte
	StatusCode      int
	Metadata        map[string]any
}

type ResponseInterceptResponse struct {
	// Headers replaces matching current response headers and preserves headers not mentioned here.
	Headers http.Header
	// Body replaces the current response body only when non-empty.
	Body []byte
	// ClearHeaders explicitly removes current response headers before Headers is applied.
	ClearHeaders []string
}

type ResponseInterceptor interface {
	InterceptResponse(context.Context, ResponseInterceptRequest) (ResponseInterceptResponse, error)
}

type ResponseNormalizer interface {
	NormalizeResponse(context.Context, ResponseTransformRequest) (PayloadResponse, error)
}

type ResponseTransformRequest struct {
	// FromFormat is the source protocol format.
	FromFormat string
	// ToFormat is the target protocol format.
	ToFormat string
	// Model is the requested model identifier.
	Model string
	// Stream reports whether the response is streaming.
	Stream bool
	// OriginalRequest contains the raw client request body.
	OriginalRequest []byte
	// TranslatedRequest contains the provider request body.
	TranslatedRequest []byte
	// Body contains the response payload to transform.
	Body []byte
}

type ResponseTranslator interface {
	TranslateResponse(context.Context, ResponseTransformRequest) (PayloadResponse, error)
}

type Scheduler interface {
	Pick(context.Context, SchedulerPickRequest) (SchedulerPickResponse, error)
}

type SchedulerAuthCandidate struct {
	// ID identifies the auth record.
	ID string
	// Provider identifies the auth provider.
	Provider string
	// Priority is the host priority assigned to the auth record.
	Priority int
	// Status is the current host-visible auth status.
	Status string
	// Attributes contains immutable routing and provider attributes.
	Attributes map[string]string
	// Metadata contains mutable host-managed auth metadata.
	Metadata map[string]any
}

type SchedulerOptions struct {
	// Headers contains request headers relevant to scheduling.
	Headers map[string][]string
	// Metadata carries host-provided scheduler context.
	Metadata map[string]any
}

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
}

type SchedulerPickResponse struct {
	// AuthID identifies the selected auth record.
	AuthID string
	// DelegateBuiltin asks the host to use a named built-in scheduler.
	DelegateBuiltin string
	// Handled reports whether the plugin made a scheduling decision.
	Handled bool
}

type StaticModelRequest struct {
	// Plugin is the metadata of the plugin being registered.
	Plugin Metadata
	// Host contains relevant host configuration.
	Host HostConfigSummary
}

type StreamChunkInterceptRequest struct {
	SourceFormat    string
	Model           string
	RequestedModel  string
	RequestHeaders  http.Header
	ResponseHeaders http.Header
	OriginalRequest []byte
	RequestBody     []byte
	Body            []byte
	// HistoryChunks contains a bounded recent history of chunks already delivered downstream.
	// The host currently retains at most 64 chunks and 1 MiB total history bytes.
	HistoryChunks [][]byte
	// ChunkIndex starts at 0 for payload chunks. StreamChunkHeaderInitIndex marks the header-only initialization call.
	ChunkIndex int
	// Metadata is a best-effort cloned context snapshot. Treat it as read-only and JSON-like.
	Metadata map[string]any
}

type StreamChunkInterceptResponse struct {
	// Headers replaces matching current stream headers and preserves headers not mentioned here.
	Headers http.Header
	// Body replaces the current stream chunk body only when non-empty.
	Body []byte
	// ClearHeaders explicitly removes current stream headers before Headers is applied.
	ClearHeaders []string
	// DropChunk skips delivery of the current payload chunk and prevents it from entering HistoryChunks.
	// Header updates returned with DropChunk still apply to the interceptor chain state.
	DropChunk bool
}

type StreamChunkInterceptor interface {
	InterceptStreamChunk(context.Context, StreamChunkInterceptRequest) (StreamChunkInterceptResponse, error)
}

type ThinkingApplier interface {
	// Identifier returns the provider key handled by this thinking applier.
	Identifier() string
	// ApplyThinking returns the payload with provider-specific thinking fields.
	ApplyThinking(context.Context, ThinkingApplyRequest) (PayloadResponse, error)
}

type ThinkingApplyRequest struct {
	// Provider is the normalized provider key being applied.
	Provider string
	// Model describes the model associated with the request.
	Model ModelInfo
	// Config is the already parsed and normalized thinking config.
	Config ThinkingConfig
	// Body contains the provider payload to rewrite.
	Body []byte
}

type ThinkingConfig struct {
	// Mode is the canonical thinking mode: budget, level, none, or auto.
	Mode string
	// Budget is the normalized thinking token budget.
	Budget int
	// Level is the normalized named thinking effort level.
	Level string
}

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
}

type UsageDetail struct {
	// InputTokens is the prompt or input token count.
	InputTokens int64
	// OutputTokens is the completion or output token count.
	OutputTokens int64
	// ReasoningTokens is the reasoning token count.
	ReasoningTokens int64
	// CachedTokens is the total cached token count.
	CachedTokens int64
	// CacheReadTokens is the cache read token count.
	CacheReadTokens int64
	// CacheCreationTokens is the cache creation token count.
	CacheCreationTokens int64
	// TotalTokens is the total token count.
	TotalTokens int64
}

type UsageFailure struct {
	// StatusCode is the HTTP status code associated with the failure.
	StatusCode int
	// Body contains the failure response body or message.
	Body string
}

type UsagePlugin interface {
	HandleUsage(context.Context, UsageRecord)
}

type UsageRecord struct {
	// Provider identifies the upstream provider.
	Provider string
	// ExecutorType identifies the executor implementation.
	ExecutorType string
	// Model is the model used for the request.
	Model string
	// Alias is the user-facing model alias when one was used.
	Alias string
	// APIKey is the client API key identifier when available.
	APIKey string
	// AuthID identifies the selected credential.
	AuthID string
	// AuthIndex identifies the credential index when applicable.
	AuthIndex string
	// AuthType identifies the credential type.
	AuthType string
	// Source identifies the request source or integration.
	Source string
	// ReasoningEffort records the requested reasoning effort.
	ReasoningEffort string
	// ServiceTier records the requested or reported service tier.
	ServiceTier string
	// RequestedAt is the time the request was received.
	RequestedAt time.Time
	// Latency is the total request latency.
	Latency time.Duration
	// TTFT is the time to first token for streaming requests.
	TTFT time.Duration
	// Failed reports whether the request failed.
	Failed bool
	// Failure contains failure details when Failed is true.
	Failure UsageFailure
	// Detail contains token usage counters.
	Detail UsageDetail
	// ResponseHeaders contains selected upstream response headers.
	ResponseHeaders http.Header
}