pluginapi

type Action string

type Attempt struct {
	// Seq is the attempt number, starting at 1.
	Seq int
	// Kind is the attempt kind, for example "primary" or "failover".
	Kind string
	// Provider is the provider type; ProviderName the instance; Model the
	// provider model.
	Provider, ProviderName, Model string
	// StatusCode is the upstream HTTP status, when known.
	StatusCode int
	// Success reports whether the attempt produced a usable response.
	Success bool
	// ErrorCode is the gateway error code when the attempt failed.
	ErrorCode string
	// Duration is the wall-clock time of the attempt.
	Duration time.Duration
}

type BuildInfo struct {
	// GoVersion is the Go toolchain version, for example "go1.27.1".
	GoVersion string
	// PluginAPIVersion is the [Version] of this package at build time.
	PluginAPIVersion string
}

type CacheInfo struct {
	// PlannedPrefixMessages is how many leading messages the provider cache
	// planner will mark as the cached prefix. Editing a message with a lower
	// index invalidates the cache for the session; appending does not.
	PlannedPrefixMessages int
	// SessionTarget is the sticky "provider/model" for the session, if any.
	SessionTarget string
}

type ChangeKind string

type Changes struct {
	// Messages maps message IDs (or "choice:<index>" for completions) to the
	// kind of change. Untouched messages are absent.
	Messages map[string]ChangeKind
	// Params holds parameters set through SetParam, by name.
	Params map[string]any
	// Dirty is true after any edit.
	Dirty bool
	// Edits counts the edit calls made so far, repeats on one message
	// included, so a host can tell whether a step edited anything.
	Edits int
}

type Choice struct {
	Index int
	// Message uses the same Part model as the request: text, tool_call,
	// reasoning, refusal.
	Message Message
	// FinishReason is the OpenAI-style reason: "stop", "length",
	// "tool_calls", "content_filter".
	FinishReason string
}

type CompleteHook interface {
	OnComplete(ctx context.Context, x *Exchange)
}

type Completion struct {
	ID      string
	Model   string
	Choices []Choice
	Usage   Usage
	// Raw is the response as received from the provider. Read-only.
	Raw json.RawMessage
	// contains filtered or unexported fields
}

type DanglingToolError struct {
	// MessageID is the removed message.
	MessageID string
	// PartnerID is the message that now lacks its call or result.
	PartnerID string
	// CallID is the tool call whose pairing broke.
	CallID string
}

type Decision struct {
	// Action selects what happens next. The zero value is treated as
	// [ActionAllow].
	Action Action
	// Status is the HTTP status for [ActionBlock], 400 to 599. Zero, or a
	// value outside that range, means the phase default: 400 in request
	// phases, 502 in response phases.
	Status int
	// Code is a machine-readable reason such as "content_policy".
	Code string
	// Message is the human-readable reason sent to the client on block.
	Message string
	// Response is the synthetic completion for [ActionRespond].
	Response *Completion
	// Detail is a JSON-serializable summary stored in the audit trail. It
	// must not contain secrets.
	Detail any
}

type EventKind string

type Exchange struct {
	// Meta is read-only identity and routing information.
	Meta Meta
	// Prompt is the unified request. Edit it through its methods.
	Prompt *Prompt
	// Response is the unified response. Edit it through its methods.
	Response *Completion
	// Stream is the accumulated stream state for streaming requests.
	Stream *StreamState
	// Headers carries inbound request headers and outbound response headers.
	Headers *Headers
	// Values is a per-request bag for passing state between a plugin's own
	// hooks (for example from OnPrompt to OnResponse). Keys should be
	// prefixed with the plugin name to avoid collisions.
	Values Values
}

type Field struct {
	// Key is the JSON key in the instance config.
	Key string
	// Label is the human-readable name shown next to the control.
	Label string
	// Input selects the control; defaults to [InputText].
	Input Input
	// Required rejects configs that omit the key.
	Required bool
	// Help is a short explanation shown under the control.
	Help string
	// Placeholder is the control's placeholder text.
	Placeholder string
	// Default is used when the key is absent. Must be JSON-serializable.
	Default any
	// Options lists the choices of select and checkboxes inputs.
	Options []Option
	// Scope selects the editor; see [FieldScope].
	Scope FieldScope
}

type FieldScope string

type Headers struct {
	// Request is a copy of the inbound headers with credential headers
	// redacted. Edits affect upstream passthrough headers and the audit
	// record.
	Request http.Header
	// Response is applied to the client response: a header set here is sent
	// with the given values. A header set to the single empty string is
	// removed from the response instead, including headers the gateway adds
	// on its own.
	Response http.Header
	// Upstream adds headers to the provider call. A host that does not
	// support it ignores the field.
	Upstream http.Header
}

type Host interface {
	// Logger returns a logger pre-tagged with the plugin and instance name.
	Logger() *slog.Logger
	// Inference runs internal chat completions through the gateway. Routing,
	// usage accounting, and budgets apply; requests carry origin "plugin".
	Inference() Inference
	// History loads earlier turns that are not in the request body: Responses
	// requests referencing previous_response_id or a conversation. Returns
	// nil, nil when there is nothing stored.
	History(ctx context.Context, meta Meta) ([]Message, error)
	// Metrics registers and updates counters and histograms under the
	// plugin's own metric namespace.
	Metrics() Metrics
}

type Inference interface {
	Complete(ctx context.Context, req InferenceRequest) (*Completion, error)
}

type InferenceRequest struct {
	// Model is a "provider/model" reference, an alias, or a virtual model.
	Model string
	// UserPath optionally overrides the user path the internal call is scoped
	// to (for budgets and audit). Empty means the current request's path.
	UserPath string
	// Messages is the conversation to send.
	Messages []Message
	// MaxTokens caps the completion length; zero leaves it to the model.
	MaxTokens int
	// Temperature is the sampling temperature; nil leaves it to the model.
	Temperature *float64
}

type Input string

type Kind string

type Manifest struct {
	// Name is the stable identifier used in configuration and workflows.
	Name string
	// Version is the plugin's own version, shown in logs and the dashboard.
	Version string
	// Description is a one-line summary for the dashboard.
	Description string
	// BuiltWith is filled by the build helper; leave empty otherwise.
	BuiltWith BuildInfo
	// Kinds lists the hooks the plugin implements.
	Kinds []Kind
	// Mutates declares that the plugin edits the Prompt, Completion, or
	// stream. Non-mutating plugins may run concurrently with the provider call.
	Mutates bool
	// Guardrail declares that the plugin's instances are guardrails: policies
	// applied to prompts, responses, or streams, whether they block, answer,
	// warn, or rewrite (a judge, a pattern blocker, a header or prompt
	// editor). Plugins that never touch traffic, such as routing strategies,
	// leave it false. The dashboard marks guardrail plugins and their
	// instances with a shield; nothing in the runtime depends on it.
	Guardrail bool
	// ConfigSchema drives the dashboard form and config validation. The
	// validated config is passed to [Plugin.Init] as JSON.
	ConfigSchema []Field
}

type Message struct {
	// ID is stable within the exchange and survives edits. The host assigns
	// IDs; messages inserted by plugins get "new-N" IDs.
	ID   string
	Role Role
	// Parts is the content in order. Tool calls follow any text.
	Parts []Part
	// Name is the optional participant name (chat "name").
	Name string
	// ToolCallID links a [RoleTool] message to the call it answers.
	ToolCallID string
	// CacheBreakpoint reports an explicit prompt-cache marker on this
	// message (Anthropic cache_control).
	CacheBreakpoint bool
}

type Meta struct {
	// RequestID is the gateway request identifier.
	RequestID string
	// Dialect is the client API dialect: "openai" or "anthropic_messages".
	Dialect string
	// Endpoint is the request URL path, for example "/v1/chat/completions".
	Endpoint string
	// Operation is the gateway operation name, for example "chat_completions".
	Operation string

	// UserPath is the effective user path the request is scoped to.
	UserPath string
	// AuthKeyID identifies the API key used, never the key itself.
	AuthKeyID string
	// Labels are the request labels attached by tagging rules.
	Labels map[string]string
	// SessionID is the detected conversation session, if any.
	SessionID string

	// RequestedModel is the model the client asked for.
	RequestedModel string
	// Provider is the resolved provider type, for example "anthropic".
	Provider string
	// ProviderName is the resolved provider instance name.
	ProviderName string
	// Model is the resolved provider model.
	Model string
	// VirtualModelSource is the virtual model that produced the resolution,
	// empty when the client addressed a provider model directly.
	VirtualModelSource string

	// WorkflowVersionID identifies the workflow version in effect.
	WorkflowVersionID string
	// Features lists workflow feature flags in effect.
	Features map[string]bool
	// Stream reports whether the client asked for a streaming response.
	Stream bool

	// Attempts lists provider attempts made so far (response phases only).
	Attempts []Attempt
	// Cache describes prompt-cache planning and session affinity.
	Cache CacheInfo
	// Origin says who issued the request: "client", "plugin", or another
	// gateway-internal source.
	Origin string
}

type Metrics interface {
	// Inc increments a counter by one.
	Inc(name string, labels map[string]string)
	// Observe records a histogram sample.
	Observe(name string, value float64, labels map[string]string)
}

type Option struct {
	// Value is stored in the config.
	Value string
	// Label is shown to the operator.
	Label string
}

type Params struct {
	// Model is the model the request is addressed to after routing.
	Model string
	// MaxTokens is the completion length cap (chat max_tokens, Responses
	// max_output_tokens); nil when unset.
	MaxTokens   *int
	Temperature *float64
	TopP        *float64
	// Stream reports a streaming request.
	Stream bool
	// ToolChoice is the tool_choice value as sent (string or object).
	ToolChoice any
	// Extra is a read-only view of the other body-level fields, keyed by
	// their JSON name.
	Extra map[string]any
}

type Part struct {
	Kind PartKind
	// Text is the content of text, reasoning, and refusal parts.
	Text string
	// MediaType is the MIME type of media parts, when known.
	MediaType string
	// Data is inline media as received; nil when URL-referenced.
	Data []byte
	// URL references remote or data-URI media.
	URL string
	// ToolCall is set for [PartToolCall].
	ToolCall *ToolCall
	// ToolResult is set for [PartToolResult].
	ToolResult *ToolResult
	// Raw is the original JSON encoding of parts GoModel keeps verbatim
	// (opaque parts, and media parts of the Responses dialect). Read-only.
	Raw json.RawMessage
}

type PartKind string

type Plugin interface {
	// Manifest describes the plugin. It must be cheap and side-effect free.
	Manifest() Manifest
	// Init receives the instance configuration (validated against
	// Manifest.ConfigSchema) and a Host for logging, metrics, and internal
	// inference. It is called once per configured instance, at startup and
	// again when an operator updates the instance.
	Init(ctx context.Context, config json.RawMessage, host Host) error
	// Close releases resources. It is called when the instance is removed or
	// replaced.
	Close(ctx context.Context) error
}

type Prompt struct {
	// Messages is the conversation in order, including system messages.
	Messages []Message
	// Tools are the tool definitions sent with the request.
	Tools []Tool
	// Params are the modelled request parameters.
	Params Params
	// Raw is the request body as received. Read-only.
	Raw json.RawMessage
	// contains filtered or unexported fields
}

type PromptHook interface {
	OnPrompt(ctx context.Context, x *Exchange) (Decision, error)
}

type RequestHook interface {
	OnRequest(ctx context.Context, x *Exchange) (Decision, error)
}

type ResponseHook interface {
	OnResponse(ctx context.Context, x *Exchange) (Decision, error)
}

type Role string

type RouteCandidate struct {
	// Provider is the provider name and Model the provider model; Qualified
	// is "provider/model".
	Provider, Model, Qualified string
	// Weight is the configured weight; zero when the route has none.
	Weight float64
	// InputPerMtok and OutputPerMtok are prices per million tokens, when
	// known.
	InputPerMtok, OutputPerMtok *float64
}

type RouteChoice struct {
	// Qualified is the chosen candidate's "provider/model".
	Qualified string
	// Reason is recorded in the audit trail.
	Reason string
}

type RouteOutcome struct {
	Source  string
	Target  RouteTarget
	Success bool
	// StatusCode is the upstream HTTP status, when known.
	StatusCode int
	Latency    time.Duration
	// Timeout reports that the attempt hit the provider timeout.
	Timeout bool
}

type RouteRequest struct {
	// Source is the virtual model being routed.
	Source string
	// SessionID is the detected session; SessionTarget the sticky
	// "provider/model" for it, when one exists.
	SessionID, SessionTarget string
	// Candidates are the eligible targets, in configured order.
	Candidates []RouteCandidate
	Meta       Meta
	// Prompt is the unified request; nil when the operation has none.
	Prompt *Prompt
	// Config is the virtual model's strategy_config as JSON.
	Config json.RawMessage
}

type RouteStrategy interface {
	Select(ctx context.Context, req RouteRequest) (RouteChoice, error)
	OnAttemptEnd(outcome RouteOutcome)
}

type RouteTarget struct {
	Provider, Model string
}

type StreamAction string

type StreamDecision struct {
	Action StreamAction
	// Text is the replacement text for [StreamReplace].
	Text string
	// Terminate is the decision rendered when the stream is cut: a block
	// error or a [Respond] completion.
	Terminate *Decision
}

type StreamEvent struct {
	// Seq is the event number, starting at 1.
	Seq  int
	Kind EventKind
	// Choice is the choice index the event belongs to.
	Choice int
	// Text is the delta text for text, tool-call argument, and reasoning
	// deltas.
	Text string
	// Overlap is the number of leading characters (runes) of Text that were
	// already presented in an earlier event of this choice: under a
	// lookbehind StreamPolicy GoModel withholds a tail of text and shows it
	// again in front of the next delta, after this plugin's earlier decision
	// was applied to it. An edit whose match ends within the first Overlap
	// characters was applied then and must not be applied again; edits that
	// extend past Overlap are new. 0 when nothing was withheld.
	Overlap int
	// Raw is the event as received. Read-only.
	Raw json.RawMessage
}

type StreamHook interface {
	StreamPolicy() StreamPolicy
	OnStreamEvent(ctx context.Context, x *Exchange, ev *StreamEvent) (StreamDecision, error)
	OnStreamEnd(ctx context.Context, x *Exchange) (Decision, error)
}

type StreamMode string

type StreamPolicy struct {
	Mode StreamMode
	// LookbehindChars is how many trailing characters GoModel withholds in
	// transform mode so the hook can rewrite text that spans events.
	LookbehindChars int
	// MaxBufferBytes caps buffering in buffer mode; zero means the host
	// default. The buffer is shared by every plugin buffering the same
	// stream, so the largest cap asked for applies, and the host default
	// when any of them asks for none.
	MaxBufferBytes int
}

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

type Tool struct {
	Name        string
	Description string
	// Parameters is the JSON schema of the tool's arguments.
	Parameters json.RawMessage
	// Raw is the tool definition as sent.
	Raw json.RawMessage
}

type ToolCall struct {
	// ID is the provider-visible call id (chat tool_calls[].id, Responses
	// call_id, Anthropic tool_use.id).
	ID string
	// Name is the tool name.
	Name string
	// Arguments is the argument JSON. When the wire format carried the
	// arguments as a string that parses as JSON, the parsed value is exposed;
	// otherwise a JSON string.
	Arguments json.RawMessage
	// Server is the MCP server name for calls routed through the MCP gateway.
	Server string
}

type ToolCallRef struct {
	// MessageID is the message holding the call.
	MessageID string
	Call      ToolCall
	// HasResult reports whether a tool result for the call is present.
	HasResult bool
}

type ToolResult struct {
	// CallID matches ToolCall.ID.
	CallID string
	// Parts is the result content: text, image, or opaque parts.
	Parts []Part
	// IsError reports a failed tool execution (Anthropic is_error).
	IsError bool
}

type Usage struct {
	InputTokens  int
	OutputTokens int
	TotalTokens  int
	// CachedInputTokens is the part of InputTokens served from a prompt cache.
	CachedInputTokens int
}

type Values map[string]any