schema

type Agent struct {
	ID      string    `json:"id"`
	Created time.Time `json:"created"`
	Version uint      `json:"version"`
	AgentMeta
}

type AgentMeta struct {
	GeneratorMeta `yaml:",inline"`
	Name          string     `json:"name" yaml:"name" help:"Unique agent name"`
	Title         string     `json:"title,omitempty" yaml:"title" help:"Human-readable title" optional:""`
	Description   string     `json:"description,omitempty" yaml:"description" help:"Agent description" optional:""`
	Template      string     `json:"template,omitempty" yaml:"-" help:"Go template for the user message" optional:""`
	Input         JSONSchema `json:"input,omitempty" yaml:"input" help:"JSON schema for agent input" optional:""`
	Tools         []string   `json:"tools,omitzero" yaml:"tools" help:"Tool names the agent is allowed to use" optional:""`
}

type AgentStore interface {
	// CreateAgent creates a new agent from the given metadata,
	// returning the agent with a unique ID and version 1.
	CreateAgent(ctx context.Context, meta AgentMeta) (*Agent, error)

	// GetAgent retrieves an existing agent by ID or name.
	// Returns an error if the agent does not exist.
	GetAgent(ctx context.Context, id string) (*Agent, error)

	// ListAgents returns agents matching the request, with pagination support.
	// Returns offset, limit and total count in the response.
	ListAgents(ctx context.Context, req ListAgentRequest) (*ListAgentResponse, error)

	// DeleteAgent removes an agent by ID or name. When a name is provided,
	// all versions of the agent are deleted. Returns an error if no matching
	// agent exists.
	DeleteAgent(ctx context.Context, id string) error

	// UpdateAgent applies non-zero fields from the given metadata to an existing
	// agent and increments the version. Returns the updated agent.
	UpdateAgent(ctx context.Context, id string, meta AgentMeta) (*Agent, error)
}

type AgentTable []*Agent

type AskRequest struct {
	AskRequestCore
	Attachments []Attachment `json:"attachments,omitempty" help:"File attachments" optional:""`
}

type AskRequestCore struct {
	GeneratorMeta
	Text string `json:"text" arg:"" help:"User input text"`
}

type AskResponse struct {
	CompletionResponse
	Usage *Usage `json:"usage,omitempty"`
}

type Attachment struct {
	Type string   `json:"type"`           // MIME type: "image/png", "application/pdf", etc.
	Data []byte   `json:"data,omitempty"` // Raw binary data
	URL  *url.URL `json:"url,omitempty"`  // URL reference (http, https, gs, file, etc.)
}

type CallToolRequest struct {
	Input json.RawMessage `json:"input,omitempty"`
}

type CallToolResponse struct {
	Tool   string          `json:"tool"`
	Result json.RawMessage `json:"result"`
}

type Capability string

type ChatRequest struct {
	ChatRequestCore
	Attachments []Attachment `json:"attachments,omitempty" help:"File attachments" optional:""`
}

type ChatRequestCore struct {
	Session       string   `json:"session" help:"Session ID"`
	Text          string   `json:"text" arg:"" help:"User input text"`
	Tools         []string `json:"tools,omitzero" help:"Tool names to include (nil means all, empty means none)" optional:""`
	MaxIterations uint     `json:"max_iterations,omitempty" help:"Maximum tool-calling iterations (0 uses default)" optional:""`
	SystemPrompt  string   `json:"system_prompt,omitempty" help:"Per-request system prompt appended to the session prompt" optional:""`
}

type ChatResponse struct {
	CompletionResponse
	Session string `json:"session"`
	Usage   *Usage `json:"usage,omitempty"`
}

type CompletionResponse struct {
	Role    string         `json:"role"`
	Content []ContentBlock `json:"content"`
	Result  ResultType     `json:"result"`
}

type Connector struct {
	// URL is the MCP server endpoint (used as the primary key).
	URL string `json:"url"`

	// CreatedAt is the time the connector was first registered.
	CreatedAt time.Time `json:"created_at"`

	// Embedded metadata and state fields
	ConnectorMeta
	ConnectorState
}

type ConnectorMeta struct {
	// Enabled controls whether the server is active. Disabled servers are
	// retained in the registry but not connected on startup.
	// A nil value in a patch request means "preserve the existing value".
	Enabled *bool `json:"enabled,omitempty"`

	// Namespace is an optional prefix used to disambiguate tools from this
	// connector when multiple connectors expose tools with the same name.
	// A nil value in a patch request means "preserve the existing value".
	Namespace *string `json:"namespace,omitempty"`
}

type ConnectorState struct {
	// ConnectedAt is the time of the most recent successful connection.
	ConnectedAt *time.Time `json:"connected_at,omitempty"`

	// Name is the programmatic identifier reported by the server.
	Name *string `json:"name,omitempty"`

	// Title is a human-readable display name reported by the server.
	Title *string `json:"title,omitempty"`

	// Description is the server-reported description.
	Description *string `json:"description,omitempty"`

	// Version is the server-reported version string.
	Version *string `json:"version,omitempty"`

	// Capabilities is the set of capabilities declared at initialization.
	Capabilities []Capability `json:"capabilities,omitempty"`
}

type ConnectorStore interface {
	// CreateConnector registers a new MCP server. url is used as the primary
	// key. Returns an error if a connector with that URL already exists.
	CreateConnector(ctx context.Context, url string, meta ConnectorMeta) (*Connector, error)

	// GetConnector returns the connector for the given URL, or an error if not found.
	GetConnector(ctx context.Context, url string) (*Connector, error)

	// UpdateConnector applies meta to the connector identified by url.
	// Only user-editable fields (ConnectorMeta) are updated; server-reported
	// fields are ignored. Returns an error if the connector does not exist.
	UpdateConnector(ctx context.Context, url string, meta ConnectorMeta) (*Connector, error)

	// DeleteConnector removes the connector for the given URL.
	DeleteConnector(ctx context.Context, url string) error

	// ListConnectors returns connectors matching the request filters.
	// Supports pagination via Offset/Limit and optional filtering by Namespace and Enabled.
	ListConnectors(ctx context.Context, req ListConnectorsRequest) (*ListConnectorsResponse, error)

	// UpdateConnectorState merges state into the connector identified by url,
	// updating only the non-nil fields in state. Intended to be called after
	// a successful connection to record server-reported information.
	// Returns an error if the connector does not exist.
	UpdateConnectorState(ctx context.Context, url string, state ConnectorState) (*Connector, error)
}

type ConnectorTable []*Connector

type ContentBlock struct {
	Text       *string     `json:"text,omitempty"`        // Text content
	Thinking   *string     `json:"thinking,omitempty"`    // Thinking/reasoning content
	Attachment *Attachment `json:"attachment,omitempty"`  // Image, document, audio, etc.
	ToolCall   *ToolCall   `json:"tool_call,omitempty"`   // Tool invocation (assistant → user)
	ToolResult *ToolResult `json:"tool_result,omitempty"` // Tool response (user → assistant)
}

type Conversation []*Message

type CreateAgentSessionRequest struct {
	Parent string          `json:"parent,omitempty" help:"Parent session ID for traceability" optional:""`
	Input  json.RawMessage `json:"input,omitempty" help:"Input data for the agent template" optional:""`
}

type CreateAgentSessionResponse struct {
	Session string   `json:"session"`         // Created session ID
	Text    string   `json:"text"`            // Rendered template text (first user message)
	Tools   []string `json:"tools,omitempty"` // Tool names the agent is allowed to use
}

type CredentialStore interface {
	// GetCredential retrieves the credential for the given server URL.
	GetCredential(ctx context.Context, url string) (*OAuthCredentials, error)

	// SetCredential stores (or updates) the credential for the given server URL.
	SetCredential(ctx context.Context, url string, cred OAuthCredentials) error

	// DeleteCredential removes the credential for the given server URL.
	DeleteCredential(ctx context.Context, url string) error
}

type EmbeddingRequest struct {
	Provider             string   `json:"provider,omitempty" help:"Provider name" optional:""`
	Model                string   `json:"model,omitempty" help:"Model name" optional:""`
	Input                []string `json:"input,omitempty" arg:"" help:"Text inputs to embed"`
	TaskType             string   `` /* 244-byte string literal not displayed */
	Title                string   `json:"title,omitempty" help:"Document title, used with RETRIEVAL_DOCUMENT task type (Google-specific)"`
	OutputDimensionality uint     `json:"output_dimensionality,omitempty" help:"Truncate embedding to this many dimensions (Google-specific)"`
}

type EmbeddingResponse struct {
	EmbeddingRequest
	Output [][]float64 `json:"output,omitempty"`
}

type GeneratorMeta struct {
	Provider       string     `json:"provider,omitempty" yaml:"provider" help:"Provider name" optional:""`
	Model          string     `json:"model,omitempty" yaml:"model" help:"Model name" optional:""`
	SystemPrompt   string     `json:"system_prompt,omitempty" yaml:"system_prompt" help:"System prompt" optional:""`
	Format         JSONSchema `json:"format,omitempty" yaml:"format" help:"JSON schema for structured output" optional:""`
	Thinking       *bool      `json:"thinking,omitempty" yaml:"thinking" help:"Enable thinking/reasoning" optional:""`
	ThinkingBudget uint       `` /* 142-byte string literal not displayed */
}

type GetModelRequest struct {
	Provider string `json:"provider,omitempty" help:"Filter by provider name" optional:""`
	Name     string `json:"name,omitempty" help:"Model name"`
}

type JSONSchema json.RawMessage

type ListAgentRequest struct {
	Name    string `json:"name,omitempty" help:"Filter by agent name" optional:""`
	Version *uint  `json:"version,omitempty" help:"Filter by version number (requires name)" optional:""`
	Limit   *uint  `json:"limit,omitempty" help:"Maximum number of agents to return" default:"100"`
	Offset  uint   `json:"offset,omitempty" help:"Offset for pagination" default:"0"`
}

type ListAgentResponse struct {
	Count  uint     `json:"count"`
	Offset uint     `json:"offset,omitzero"`
	Limit  *uint    `json:"limit,omitzero"`
	Body   []*Agent `json:"body,omitzero"`
}

type ListConnectorsRequest struct {
	Namespace string `json:"namespace,omitempty" help:"Filter by namespace" optional:""`
	Enabled   *bool  `json:"enabled,omitempty" help:"Filter by enabled state" optional:""`
	Limit     *uint  `json:"limit,omitempty" help:"Maximum number of connectors to return" default:"100"`
	Offset    uint   `json:"offset,omitempty" help:"Offset for pagination" default:"0"`
}

type ListConnectorsResponse struct {
	Count  uint         `json:"count"`
	Offset uint         `json:"offset,omitzero"`
	Limit  *uint        `json:"limit,omitzero"`
	Body   []*Connector `json:"body,omitzero"`
}

type ListModelsRequest struct {
	Provider string `json:"provider,omitempty" help:"Filter by provider name" optional:""`
	Limit    *uint  `json:"limit,omitempty" help:"Maximum number of models to return" default:"100"`
	Offset   uint   `json:"offset,omitempty" help:"Offset for pagination" default:"0"`
}

type ListModelsResponse struct {
	Count    uint     `json:"count"`
	Offset   uint     `json:"offset,omitzero"`
	Limit    *uint    `json:"limit,omitzero"`
	Provider []string `json:"provider,omitempty"`
	Body     []Model  `json:"body,omitzero"`
}

type ListSessionRequest struct {
	Limit  *uint    `json:"limit,omitempty" help:"Maximum number of sessions to return" default:"100"`
	Offset uint     `json:"offset,omitempty" help:"Offset for pagination" default:"0"`
	Label  []string `json:"label,omitempty" help:"Filter by labels (key:value)"`
}

type ListSessionResponse struct {
	Count  uint       `json:"count"`
	Offset uint       `json:"offset,omitzero"`
	Limit  *uint      `json:"limit,omitzero"`
	Body   []*Session `json:"body,omitzero"`
}

type ListToolRequest struct {
	Limit  *uint `json:"limit,omitempty" help:"Maximum number of tools to return" default:"100"`
	Offset uint  `json:"offset,omitempty" help:"Offset for pagination" default:"0"`
}

type ListToolResponse struct {
	Count  uint       `json:"count"`
	Offset uint       `json:"offset,omitzero"`
	Limit  *uint      `json:"limit,omitzero"`
	Body   []ToolMeta `json:"body,omitzero"`
}

type ListToolsRequest struct {
	// Namespace restricts results to a single namespace.
	// Use BuiltinNamespace for locally-implemented tools, a connector URL for
	// remote tools, or leave empty to include all namespaces.
	Namespace string `json:"namespace,omitempty"`

	// Name restricts results to tools whose names appear in this list.
	// An empty slice means no name filter — all names are included.
	Name []string `json:"name,omitempty"`
}

type Message struct {
	Role    string         `json:"role"`             // "user", "assistant", "system"
	Content []ContentBlock `json:"content"`          // Array of content blocks
	Tokens  uint           `json:"tokens,omitempty"` // Number of tokens
	Result  ResultType     `json:"result"`           // Result type
	Meta    map[string]any `json:"meta,omitzero"`    // Provider-specific metadata
}

type Model struct {
	Name        string         `json:"name,omitzero"`
	Description string         `json:"description,omitzero"`
	Created     time.Time      `json:"created,omitzero"`
	OwnedBy     string         `json:"owned_by,omitzero"` // Model provider
	Aliases     []string       `json:"aliases,omitzero"`  // Model aliases
	Meta        map[string]any `json:"meta,omitzero"`     // Provider-specific metadata
}

type ModelTable struct {
	Models       []Model
	CurrentModel string
}

type MultipartAskRequest struct {
	AskRequest
	File types.File `json:"file,omitempty" help:"File attachment (multipart upload)" optional:""`
}

type MultipartChatRequest struct {
	ChatRequest
	File types.File `json:"file,omitempty" help:"File attachment (multipart upload)" optional:""`
}

type OAuthCredentials struct {
	*oauth2.Token

	// ClientID is the OAuth client ID used to obtain this token.
	ClientID string `json:"client_id"`

	// ClientSecret is the OAuth client secret, if any (for confidential clients).
	// Needed for token refresh with servers that require client authentication.
	ClientSecret string `json:"client_secret,omitempty"`

	// Endpoint is the MCP/OAuth server endpoint (used for discovery).
	Endpoint string `json:"endpoint"`

	// TokenURL is the OAuth token endpoint URL (used for refresh without re-discovery).
	TokenURL string `json:"token_url"`
}

type ProviderTable []string

type ResultType uint

type Session struct {
	ID string `json:"id"`
	SessionMeta
	Messages Conversation `json:"messages,omitempty"`
	Overhead uint         `json:"overhead,omitempty"` // Constant token cost per turn (tools, system prompt)
	Created  time.Time    `json:"created"`
	Modified time.Time    `json:"modified"`
}

type SessionMeta struct {
	GeneratorMeta
	Name   string            `json:"name,omitempty" help:"Session name" optional:""`
	Labels map[string]string `json:"labels,omitempty" help:"User-defined labels for UI storage" optional:""`
}

type SessionStore interface {
	// CreateSession creates a new session from the given metadata,
	// returning the session with a unique ID assigned.
	CreateSession(ctx context.Context, meta SessionMeta) (*Session, error)

	// GetSession retrieves an existing session by ID.
	// Returns an error if the session does not exist.
	GetSession(ctx context.Context, id string) (*Session, error)

	// ListSessions returns sessions matching the request, with pagination support.
	// Returns offset, limit and total count in the response.
	ListSessions(ctx context.Context, req ListSessionRequest) (*ListSessionResponse, error)

	// DeleteSession removes a session by ID.
	// Returns an error if the session does not exist.
	DeleteSession(ctx context.Context, id string) error

	// UpdateSession applies non-zero fields from the given metadata to an existing session.
	// Returns the updated session or an error if the session does not exist.
	UpdateSession(ctx context.Context, id string, meta SessionMeta) (*Session, error)

	// WriteSession persists the current state of a session.
	WriteSession(s *Session) error
}

type SessionTable struct {
	Sessions       []*Session
	CurrentSession string
}

type StreamDelta struct {
	Role string `json:"role"`
	Text string `json:"text"`
}

type StreamError struct {
	Error string `json:"error"`
}

type ToolCall struct {
	ID    string          `json:"id,omitempty"`    // Provider-assigned call ID
	Name  string          `json:"name"`            // Tool function name
	Input json.RawMessage `json:"input,omitempty"` // JSON-encoded arguments
	Meta  map[string]any  `json:"meta,omitempty"`  // Provider-specific metadata (e.g. thought_signature)
}

type ToolMeta struct {
	Name        string     `json:"name"`
	Description string     `json:"description,omitempty"`
	Input       JSONSchema `json:"input,omitempty"`
}

type ToolResult struct {
	ID      string          `json:"id,omitempty"`      // Matches the ToolCall ID
	Name    string          `json:"name,omitempty"`    // Tool function name
	Content json.RawMessage `json:"content,omitempty"` // JSON-encoded result
	IsError bool            `json:"is_error,omitempty"`
}

type ToolTable []ToolMeta

type Usage struct {
	InputTokens  uint `json:"input_tokens,omitempty"`
	OutputTokens uint `json:"output_tokens,omitempty"`
}