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

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

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
}

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
}

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

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
}

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

type ManagementRegistrationResponse struct {
	// Routes contains the exact Management API routes to expose.
	Routes []ManagementRoute
}

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 the optional management UI menu label for GET routes.
	Menu string
	// Description explains the management route 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 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 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 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 StaticModelRequest struct {
	// Plugin is the metadata of the plugin being registered.
	Plugin Metadata
	// Host contains relevant host configuration.
	Host HostConfigSummary
}

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
}