chat

type Acceptance struct {
	Response Response  // Identity for new work; ignored when Replay is set.
	Replay   *Response // When set, skip Agent.Run and encode this result.

	// Agent, when non-nil, is the request-specific executable for this
	// acceptance. It replaces the Catalog agent for Agent.Run only. Catalog.Load
	// still authorizes discovery-independent invocation and supplies Info.
	// When set, llmux does not load or merge continuation history into
	// Request.Input: the Agent owns effective input. Nil keeps the Catalog
	// agent and the ordinary post-Accept history merge for Previous.
	Agent Agent

	// RunTimeout controls execution cancellation:
	//   0  — follow the HTTP request context (cancel on client disconnect)
	//   >0 — detach client cancel, preserve values, bound by this duration;
	//        llmux owns cancel and releases it on every exit. Delivery
	//        failures after disconnect do not cancel execution.
	//   <0 — invalid; the handler rejects and calls Finish when set so
	//        reserved resources cannot leak.
	RunTimeout time.Duration
	Activity   bool // When true, Responses may emit EventActivity.

	// Finish is called exactly once after Agent.Run for a new acceptance.
	// Nil when Replay is set or when no terminal persistence is needed.
	// The Response is read-only and shared with subsequent encoding; Clone
	// before retaining or modifying. err is the operational execution error.
	Finish func(context.Context, *Response, error) error
}

type Agent interface {
	// Run executes once for an accepted HTTP request and streams events through emit.
	// It must stop when emit returns an error.
	Run(context.Context, *Request, Emit) (Outcome, error)
}

type AgentFunc func(context.Context, *Request, Emit) (Outcome, error)

type AssetResolver func(context.Context, Media, int64) (Media, error)

type AudioControls struct {
	Voice  string
	Format string
}

type Controls struct {
	MaxOutputTokens  *int                      // Maximum tokens to generate.
	Temperature      *float64                  // Sampling temperature.
	TopP             *float64                  // Nucleus sampling threshold.
	Stop             []string                  // Stop sequences.
	Tools            []FunctionTool            // Function tools available to the model.
	ToolChoice       *ToolChoice               // Tool selection policy.
	ParallelToolCall *bool                     // Whether parallel tool calls are allowed.
	Reasoning        *ReasoningControl         // Reasoning effort and summary controls.
	Audio            *AudioControls            // Chat Completions audio output controls.
	ImageGeneration  bool                      // Whether image generation is requested.
	Extensions       map[string]jsontext.Value // Application extension payloads keyed by name.
}

type Emit func(Event) error

type Error struct {
	Status  int
	Type    string
	Code    string
	Param   string
	Message string
	Err     error
}

type Event struct {
	Type   EventType
	ItemID string
	CallID string
	Name   string
	Delta  string
	Item   Item
	Data   jsontext.Value
}

type EventType string

type FormatKind string

type FunctionTool struct {
	Name        string         `json:"name"`
	Description string         `json:"description,omitempty"`
	Parameters  jsontext.Value `json:"parameters,omitempty"`
	Strict      *bool          `json:"strict,omitempty"`
}

type GenerationControl uint16

type Info struct {
	InputModalities    Modality
	OutputModalities   Modality
	GenerationControls GenerationControl
	Extensions         map[string]bool
	Tools              bool
	ClientTools        bool
	StructuredOutput   bool
	ReasoningSummary   bool
	ImageGeneration    bool
	Continuation       bool

	// Description is a human-readable summary of the agent. Resolver
	// implementations should set it; llmux surfaces it as the MCP tool
	// description when the agent is exposed through /mcp.
	Description string

	// Tool is the stable public MCP tool name for this agent. Empty means
	// the agent is not exposed through MCP; nonempty exposes it, with the
	// name owned by the application (1-128 characters from [A-Za-z0-9._-],
	// unique per catalog). It is never derived from the resolver target.
	Tool string

	// Created is the Unix creation time in seconds shown in the model
	// catalog. Zero is rendered as the zero time value.
	Created int64
	// OwnedBy is the owner label shown in the model catalog.
	OwnedBy string
}

type Item struct {
	Type             ItemType       `json:"type"`
	ID               string         `json:"id,omitempty"`
	Status           Status         `json:"status,omitempty"`
	Role             Role           `json:"role,omitempty"`
	Content          []Part         `json:"content,omitempty"`
	CallID           string         `json:"call_id,omitempty"`
	Name             string         `json:"name,omitempty"`
	Arguments        string         `json:"arguments,omitempty"`
	Output           []Part         `json:"output,omitempty"`
	Summary          []Part         `json:"summary,omitempty"`
	EncryptedContent jsontext.Value `json:"encrypted_content,omitempty"`
	Data             jsontext.Value `json:"data,omitempty"`
}

type ItemType string

type Limits struct {
	MaxRequestBytes   int64
	MaxMediaBytes     int64
	MaxAssets         int
	MaxOutputBytes    int64
	MaxEventBytes     int64
	MaxMultipartBytes int64
}

type Media struct {
	MIMEType string `json:"mime_type,omitempty"`
	Format   string `json:"format,omitempty"`
	Filename string `json:"filename,omitempty"`
	URL      string `json:"url,omitempty"`
	Ref      string `json:"ref,omitempty"`
	Data     []byte `json:"data,omitempty"`
}

type Modality uint8

type Outcome struct {
	Status     Status
	StopReason StopReason
	Usage      *Usage
}

type OutputFormat struct {
	Kind        FormatKind
	Name        string
	Description string
	Schema      jsontext.Value
	Strict      bool
}

type OutputSpec struct {
	Modalities Modality
	Format     OutputFormat
}

type Part struct {
	Type     PartType       `json:"type"`
	Text     string         `json:"text,omitempty"`
	Media    *Media         `json:"media,omitempty"`
	Data     jsontext.Value `json:"data,omitempty"`
	Detail   string         `json:"detail,omitempty"`
	Filename string         `json:"filename,omitempty"`
}

type PartType string

type ReasoningControl struct {
	Effort  string
	Summary bool
}

type Request struct {
	Target       string     // Agent target name selected by the resolver.
	Instructions string     // System or developer instructions for the run.
	Input        []Item     // Effective conversation for Agent.Run (history+turn).
	Controls     Controls   // Generation settings.
	Output       OutputSpec // Declared output modalities and format.
}

type Response struct {
	ID           string            // Response identifier
	Created      int64             // Unix creation time
	CompletedAt  int64             // Unix completion time; zero while in_progress
	Status       Status            // completed, failed, incomplete, cancelled, or in_progress
	Output       []Item            // Output items for this response turn
	Usage        *Usage            // Token usage when known
	Error        *Error            // Sanitized public error when status is failed
	Incomplete   string            // incomplete_details.reason when status is incomplete
	Metadata     map[string]string // Response metadata captured at acceptance
	Store        bool              // Effective content-retention policy
	Target       string            // Model/target echoed for retrieval
	Instructions string            // Instructions echoed for retrieval
	Previous     *string           // Parent response ID for retrieval
}

type Role string

type Status string

type StopReason string

type ToolChoice struct {
	Mode string
	Name string
}

type TurnRequest struct {
	Request        *Request          // Execution request; treat as read-only.
	Turn           []Item            // Items submitted in this request only.
	Previous       *string           // Prior response ID for continuation.
	Metadata       map[string]string // Application metadata for the response.
	Store          *bool             // Wire store flag; nil when omitted.
	Retain         bool              // Effective retention after StoreDefault.
	IdempotencyKey string            // Idempotency-Key header value, if any.
	Stream         bool              // Whether the client requested streaming.
	CatalogAgent   Agent             // Agent from Catalog.Load for this target.
}

type Usage struct {
	Input     int
	Output    int
	Total     int
	Cached    int
	Reasoning int
}