core

type Agent[T any] struct {
	// contains filtered or unexported fields
}

type AgentExecutionFeatures struct {
	DynamicSystemPrompts       int
	HistoryProcessors          int
	Toolsets                   int
	HasAgentToolsPrepare       bool
	ToolsWithPrepareFunc       int
	ToolsWithResultValidator   int
	ToolsRequiringApproval     int
	HasToolApprovalFunc        bool
	Hooks                      int
	InputGuardrails            int
	TurnGuardrails             int
	OutputValidators           int
	HasOutputRepair            bool
	GlobalToolResultValidators int
	RunConditions              int
	TraceExporters             int
	HasEventBus                bool
	HasAgentDeps               bool
	MessageInterceptors        int
	ResponseInterceptors       int
	HasKnowledgeBase           bool
	HasKnowledgeAutoStore      bool
	HasCostTracker             bool
	HasAutoContext             bool
	HasUsageQuota              bool
	RequestMiddleware          int
	StreamMiddleware           int
}

type AgentMiddleware struct {
	Request RequestMiddlewareFunc
	Stream  AgentStreamMiddleware
}

type AgentOption[T any] func(*Agent[T])

type AgentRun[T any] struct {
	// contains filtered or unexported fields
}

type AgentRunError struct {
	Message string
}

type AgentRuntimeConfig[T any] struct {
	SystemPrompts              []string
	DynamicSystemPrompts       []SystemPromptFunc
	HistoryProcessors          []HistoryProcessor
	Tools                      []Tool
	Hooks                      []Hook
	InputGuardrails            []InputGuardrailRuntime
	TurnGuardrails             []TurnGuardrailRuntime
	AgentToolsPrepare          AgentToolsPrepareFunc
	OutputSchema               *OutputSchema
	OutputValidators           []OutputValidatorFunc[T]
	OutputRepair               RepairFunc[T]
	ModelSettings              *ModelSettings
	UsageLimits                UsageLimits
	UsageQuota                 *UsageQuota
	MaxRetries                 int
	EndStrategy                EndStrategy
	MaxConcurrency             int
	DefaultToolTimeout         time.Duration
	ToolChoice                 *ToolChoice
	ToolChoiceAutoReset        bool
	ToolApprovalFunc           ToolApprovalFunc
	GlobalToolResultValidators []ToolResultValidatorFunc
	RequestMiddleware          []RequestMiddlewareFunc
	StreamMiddleware           []AgentStreamMiddleware
	MessageInterceptors        []MessageInterceptor
	ResponseInterceptors       []ResponseInterceptor
	RunConditions              []RunCondition
	TracingEnabled             bool
	TraceExporters             []TraceExporter
	ModelName                  string
	HasCostTracker             bool
	CostPricing                map[string]ModelPricing
	CostCurrency               string
	EventBus                   *EventBus
	AgentDeps                  any
	AutoContext                *AutoContextConfig
	KnowledgeBase              KnowledgeBase
	KnowledgeAutoStore         bool
}

type AgentStreamFunc func(
	ctx context.Context,
	messages []ModelMessage,
	settings *ModelSettings,
	params *ModelRequestParameters,
) (StreamedResponse, error)

type AgentStreamMiddleware func(
	ctx context.Context,
	messages []ModelMessage,
	settings *ModelSettings,
	params *ModelRequestParameters,
	next AgentStreamFunc,
) (StreamedResponse, error)

type AgentToolsPrepareFunc func(ctx context.Context, rc *RunContext, tools []ToolDefinition) []ToolDefinition

type AudioPart struct {
	URL       string // audio URL or data: URI
	MIMEType  string // e.g., "audio/mp3", "audio/wav"
	Timestamp time.Time
}

type AutoContextConfig struct {
	MaxTokens    int   // maximum token estimate before summarization
	KeepLastN    int   // number of recent messages to always keep (default: 4)
	SummaryModel Model // model to use for summarization (optional, uses agent model if nil)
}

type BatchResult[T any] struct {
	Index  int           // position in the input slice
	Result *RunResult[T] // non-nil on success
	Err    error         // non-nil on failure
}

type CallDeferred struct {
	Message string
}

type CompactionCallback func(stats ContextCompactionStats)

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

type ContentFilterError struct {
	UnexpectedModelBehavior
}

type ContextCompactionStats struct {
	// Strategy identifies the compaction mechanism (use CompactionStrategy* constants).
	Strategy string

	// MessagesBefore is the message count before compaction.
	MessagesBefore int
	// MessagesAfter is the message count after compaction.
	MessagesAfter int

	// EstimatedTokensBefore is the estimated token count before compaction.
	EstimatedTokensBefore int
	// EstimatedTokensAfter is the estimated token count after compaction.
	EstimatedTokensAfter int
}

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

type DeferredToolRequest struct {
	ToolName   string `json:"tool_name"`
	ToolCallID string `json:"tool_call_id"`
	ArgsJSON   string `json:"args_json"`
}

type DeferredToolResult struct {
	ToolName   string `json:"tool_name"`
	ToolCallID string `json:"tool_call_id"`
	Content    string `json:"content"`
	IsError    bool   `json:"is_error,omitempty"`
}

type DocumentPart struct {
	URL       string // document URL or data: URI
	MIMEType  string // e.g., "application/pdf"
	Title     string // optional display title
	Timestamp time.Time
}

type EndStrategy string

type ErrDeferred[T any] struct {
	Result RunResultDeferred[T]
}

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

type FinishReason string

type GuardrailError struct {
	GuardrailName string
	Message       string
}

type HistoryProcessor func(ctx context.Context, messages []ModelMessage) ([]ModelMessage, error)

type Hook struct {
	// OnRunStart fires when an agent run begins.
	OnRunStart func(ctx context.Context, rc *RunContext, prompt string)
	// OnRunEnd fires when an agent run completes (success or error).
	OnRunEnd func(ctx context.Context, rc *RunContext, messages []ModelMessage, err error)
	// OnModelRequest fires before each model request.
	OnModelRequest func(ctx context.Context, rc *RunContext, messages []ModelMessage)
	// OnModelResponse fires after each model response.
	OnModelResponse func(ctx context.Context, rc *RunContext, response *ModelResponse)
	// OnToolStart fires before a tool executes.
	OnToolStart func(ctx context.Context, rc *RunContext, toolCallID string, toolName string, argsJSON string)
	// OnToolEnd fires after a tool completes.
	OnToolEnd func(ctx context.Context, rc *RunContext, toolCallID string, toolName string, result string, err error)
	// OnTurnStart fires at the beginning of each agent loop iteration (turn).
	OnTurnStart func(ctx context.Context, rc *RunContext, turnNumber int)
	// OnTurnEnd fires at the end of each agent loop iteration (turn).
	OnTurnEnd func(ctx context.Context, rc *RunContext, turnNumber int, response *ModelResponse)
	// OnGuardrailEvaluated fires after a guardrail (input or turn) is evaluated.
	OnGuardrailEvaluated func(ctx context.Context, rc *RunContext, name string, passed bool, err error)
	// OnOutputValidation fires after structured output validation completes.
	OnOutputValidation func(ctx context.Context, rc *RunContext, passed bool, err error)
	// OnOutputRepair fires when output repair is attempted.
	OnOutputRepair func(ctx context.Context, rc *RunContext, succeeded bool, err error)
	// OnRunConditionChecked fires when a run condition is evaluated and stops the run.
	OnRunConditionChecked func(ctx context.Context, rc *RunContext, stopped bool, reason string)
	// OnContextCompaction fires when the message history is compressed to
	// fit within the context window. This includes auto-summarization
	// (AutoContext) and emergency truncation (ContextOverflowMiddleware).
	OnContextCompaction func(ctx context.Context, rc *RunContext, stats ContextCompactionStats)
}

type ImagePart struct {
	URL       string // image URL (https or data: URI with base64)
	MIMEType  string // e.g., "image/png", "image/jpeg"
	Detail    string // "auto", "low", "high" (optional)
	Timestamp time.Time
}

type IncompleteToolCall struct {
	UnexpectedModelBehavior
}

type InputGuardrailFunc func(ctx context.Context, prompt string) (string, error)

type InputGuardrailRuntime struct {
	Name string
	Func InputGuardrailFunc
}

type InterceptResult struct {
	Action   MessageAction
	Messages []ModelMessage // used when Action == MessageModify
	Reason   string         // optional reason for drop/modify
}

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

type JSONSchemaer interface {
	JSONSchema() Schema
}

type KnowledgeBase interface {
	// Retrieve fetches context relevant to the given query.
	// Returns an empty string if no relevant context is found.
	Retrieve(ctx context.Context, query string) (string, error)

	// Store persists content (e.g., successful agent responses) for future retrieval.
	Store(ctx context.Context, content string) error
}

type MessageAction int

type MessageInterceptor func(ctx context.Context, messages []ModelMessage) InterceptResult

type Model interface {
	// Request sends messages and returns a complete response.
	Request(ctx context.Context, messages []ModelMessage, settings *ModelSettings, params *ModelRequestParameters) (*ModelResponse, error)

	// RequestStream sends messages and returns an event stream for
	// incremental consumption. Providers that don't support streaming
	// should return an error.
	RequestStream(ctx context.Context, messages []ModelMessage, settings *ModelSettings, params *ModelRequestParameters) (StreamedResponse, error)

	// ModelName returns the identifier of the model (e.g., "claude-sonnet-4-5").
	ModelName() string
}

type ModelHTTPError struct {
	Message    string
	StatusCode int
	Body       string
	ModelName  string
	RetryAfter time.Duration // parsed from Retry-After header, if present
}

type ModelMessage interface {
	// contains filtered or unexported methods
}

type ModelPricing struct {
	InputTokenCost  float64 // cost per input token (e.g., 0.000003 for $3/1M)
	OutputTokenCost float64 // cost per output token
	CachedInputCost float64 // cost per cached input token read (0 = same as input)
	CacheWriteCost  float64 // cost per cache write token (0 = same as input)
}

type ModelRequest struct {
	Parts     []ModelRequestPart
	Timestamp time.Time
}

type ModelRequestParameters struct {
	// FunctionTools are the callable tools available to the model.
	FunctionTools []ToolDefinition

	// OutputMode determines how structured output is extracted.
	OutputMode OutputMode

	// OutputTools are synthetic tools for structured output extraction.
	OutputTools []ToolDefinition

	// OutputObject describes the output schema for native/prompted modes.
	OutputObject *OutputObjectDefinition

	// AllowTextOutput controls whether the model can return text directly.
	AllowTextOutput bool
}

type ModelRequestPart interface {
	// contains filtered or unexported methods
}

type ModelResponse struct {
	Parts        []ModelResponsePart
	Usage        Usage
	ModelName    string
	FinishReason FinishReason
	Timestamp    time.Time
}

type ModelResponsePart interface {
	// contains filtered or unexported methods
}

type ModelResponsePartDelta interface {
	// contains filtered or unexported methods
}

type ModelResponseStreamEvent interface {
	// contains filtered or unexported methods
}

type ModelRetryError struct {
	Message string
}

type ModelSettings struct {
	MaxTokens       *int        `json:"max_tokens,omitempty"`
	Temperature     *float64    `json:"temperature,omitempty"`
	TopP            *float64    `json:"top_p,omitempty"`
	ToolChoice      *ToolChoice `json:"tool_choice,omitempty"`
	ThinkingBudget  *int        `json:"thinking_budget,omitempty"`  // Anthropic extended thinking budget tokens
	ReasoningEffort *string     `json:"reasoning_effort,omitempty"` // OpenAI o-series: "low", "medium", "high"
}

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

type OutputMode string

type OutputObjectDefinition struct {
	Name        string
	Description string
	JSONSchema  Schema
	Strict      *bool
}

type OutputOption func(*outputConfig)

type OutputSchema struct {
	// Mode is the output extraction mode.
	Mode OutputMode

	// OutputTools contains the synthetic tool definitions for tool-based output.
	OutputTools []ToolDefinition

	// OutputObject describes the schema for native structured output.
	OutputObject *OutputObjectDefinition

	// AllowsText is true when text output is acceptable (e.g., T is string).
	AllowsText bool

	// OuterTypedDictKey is set when the output type is wrapped in an object.
	OuterTypedDictKey string
	// contains filtered or unexported fields
}

type OutputValidatorFunc[T any] func(ctx context.Context, rc *RunContext, output T) (T, error)

type PartDeltaEvent struct {
	Index int
	Delta ModelResponsePartDelta
}

type PartEndEvent struct {
	Index int
}

type PartStartEvent struct {
	Index int
	Part  ModelResponsePart
}

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

type QuotaExceededError struct {
	Quota   UsageQuota
	Usage   RunUsage
	Message string
}

type ReflectOption func(*reflectConfig)

type ReflectResult[T any] struct {
	// Output is the final (possibly corrected) output.
	Output T
	// Iterations is the number of reflection iterations performed.
	Iterations int
	// Usage is the combined usage across all iterations.
	Usage RunUsage
	// Accepted indicates whether the output was accepted by the validator.
	Accepted bool
}

type RepairFunc[T any] func(ctx context.Context, raw string, parseErr error) (T, error)

type RequestMiddlewareFunc func(
	ctx context.Context,
	messages []ModelMessage,
	settings *ModelSettings,
	params *ModelRequestParameters,
	next func(context.Context, []ModelMessage, *ModelSettings, *ModelRequestParameters) (*ModelResponse, error),
) (*ModelResponse, error)

type ResponseInterceptor func(ctx context.Context, response *ModelResponse) InterceptResult

type RetryPromptPart struct {
	Content    string // error message or validation feedback
	ToolName   string // the tool that should be retried (empty for result retry)
	ToolCallID string // the tool call ID being retried
	Timestamp  time.Time
}

type RunCompletedEvent struct {
	RunID       string
	ParentRunID string
	Success     bool
	Error       string
	StartedAt   time.Time
	CompletedAt time.Time
}

type RunCondition func(ctx context.Context, rc *RunContext, resp *ModelResponse) (stop bool, reason string)

type RunConditionError struct {
	Reason string
}

type RunContext struct {
	Deps         any            // user-provided dependencies
	Usage        RunUsage       // current usage
	Prompt       string         // the user prompt
	Retry        int            // current retry count for this tool
	MaxRetries   int            // max retries configured
	ToolName     string         // name of the current tool
	ToolCallID   string         // ID of the current tool call
	Messages     []ModelMessage // conversation history (read-only)
	RunStep      int            // current step number
	RunID        string         // unique run ID
	ParentRunID  string         // parent run ID when this run was started by another run
	RunStartTime time.Time      // when the current run started
	EventBus     *EventBus      // event bus for agent coordination (nil if not configured)

	// Detach is closed by the UI layer to signal that the currently running
	// tool should move its work to the background and return immediately.
	// Tools that support detach (e.g., bash) select on this channel alongside
	// their blocking operation. Nil means detach is not supported.
	Detach <-chan struct{}
	// contains filtered or unexported fields
}

type RunCost struct {
	TotalCost float64            `json:"total_cost"`
	Breakdown map[string]float64 `json:"breakdown"`
	Currency  string             `json:"currency"`
}

type RunOption func(*runConfig)

type RunResult[T any] struct {
	// Output is the parsed/validated output of type T.
	Output T
	// Messages is the full conversation history.
	Messages []ModelMessage
	// Usage is the aggregate token usage for this run.
	Usage RunUsage
	// RunID is the unique identifier for this run.
	RunID string
	// Trace is the execution trace when WithTracing is enabled. Nil otherwise.
	Trace *RunTrace
	// Cost is the estimated cost when a CostTracker is configured. Nil otherwise.
	Cost *RunCost
	// ToolState is the exported state of stateful tools at the end of this run.
	// Pass this to WithToolState() on the next Run() to restore tool state
	// across turns in a multi-turn conversation.
	ToolState map[string]any
}

type RunResultDeferred[T any] struct {
	DeferredRequests []DeferredToolRequest
	Messages         []ModelMessage
	Usage            RunUsage
}

type RunSnapshot = RunStateSnapshot

type RunStartedEvent struct {
	RunID       string
	ParentRunID string
	Prompt      string
	StartedAt   time.Time
}

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

type RunStateSnapshot struct {
	Messages        []ModelMessage `json:"-"` // excluded from default JSON
	Usage           RunUsage       `json:"usage"`
	LastInputTokens int            `json:"last_input_tokens"`
	Retries         int            `json:"retries"`
	ToolRetries     map[string]int `json:"tool_retries,omitempty"`
	RunID           string         `json:"run_id"`
	ParentRunID     string         `json:"parent_run_id,omitempty"`
	RunStep         int            `json:"run_step"`
	RunStartTime    time.Time      `json:"run_start_time"`
	Prompt          string         `json:"prompt"`
	ToolState       map[string]any `json:"tool_state,omitempty"`
	Timestamp       time.Time      `json:"timestamp"`
}

type RunTrace struct {
	RunID     string        `json:"run_id"`
	Prompt    string        `json:"prompt"`
	StartTime time.Time     `json:"start_time"`
	EndTime   time.Time     `json:"end_time"`
	Duration  time.Duration `json:"duration"`
	Steps     []TraceStep   `json:"steps"`
	Usage     RunUsage      `json:"usage"`
	Success   bool          `json:"success"`
	Error     string        `json:"error,omitempty"`
}

type RunUsage struct {
	Usage
	Requests  int `json:"requests"`
	ToolCalls int `json:"tool_calls"`
}

type RuntimeEvent interface {
	RuntimeEventType() string
	RuntimeRunID() string
	RuntimeParentRunID() string
	RuntimeOccurredAt() time.Time
}

type Schema = map[string]any

type SerializedMessage = messageEnvelope

type SerializedPart = partEnvelope

type SerializedRunSnapshot struct {
	Messages        []SerializedMessage `json:"messages"`
	Usage           RunUsage            `json:"usage"`
	LastInputTokens int                 `json:"last_input_tokens"`
	Retries         int                 `json:"retries"`
	ToolRetries     map[string]int      `json:"tool_retries,omitempty"`
	RunID           string              `json:"run_id"`
	ParentRunID     string              `json:"parent_run_id,omitempty"`
	RunStep         int                 `json:"run_step"`
	RunStartTime    time.Time           `json:"run_start_time"`
	Prompt          string              `json:"prompt"`
	ToolState       map[string]any      `json:"tool_state,omitempty"`
	Timestamp       time.Time           `json:"timestamp"`
}

type StatefulTool interface {
	ExportState() (any, error)
	RestoreState(state any) error
}

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

type StreamResult[T any] struct {
	// contains filtered or unexported fields
}

type StreamedResponse interface {
	// Next returns the next stream event. Returns io.EOF when the stream is done.
	Next() (ModelResponseStreamEvent, error)

	// Response returns the ModelResponse built from data received so far.
	Response() *ModelResponse

	// Usage returns usage information gathered so far.
	Usage() Usage

	// Close cleans up resources (HTTP connections, etc.).
	Close() error
}

type SystemPromptFunc func(ctx context.Context, runCtx *RunContext) (string, error)

type SystemPromptPart struct {
	Content   string
	Timestamp time.Time
}

type TemplateVars interface {
	TemplateVars() map[string]string
}

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

type TestModelCall struct {
	Messages   []ModelMessage
	Settings   *ModelSettings
	Parameters *ModelRequestParameters
}

type TextPart struct {
	Content string
}

type TextPartDelta struct {
	ContentDelta string
}

type ThinkingPart struct {
	Content   string
	Signature string // provider-specific signature
}

type ThinkingPartDelta struct {
	ContentDelta string
}

type Tool struct {
	Definition       ToolDefinition
	Handler          ToolHandler
	MaxRetries       *int                    // nil = use agent default
	RequiresApproval bool                    // if true, the agent's ToolApprovalFunc must approve before execution
	PrepareFunc      ToolPrepareFunc         // if set, called before each model request to filter/modify this tool
	Stateful         StatefulTool            // if set, state is saved/restored with checkpoints
	ResultValidator  ToolResultValidatorFunc // if set, validates tool results before passing to model
	Timeout          time.Duration           // if > 0, tool execution is limited to this duration
}

type ToolApprovalFunc func(ctx context.Context, toolName string, argsJSON string) (bool, error)

type ToolCallPart struct {
	ToolName   string
	ArgsJSON   string // raw JSON arguments
	ToolCallID string
	// Metadata carries provider-specific opaque data that must be round-tripped
	// (e.g., Gemini 3.x thought signatures). Providers set this on parse and
	// read it back when serializing tool calls in conversation history.
	Metadata map[string]string
}

type ToolCallPartDelta struct {
	ArgsJSONDelta string
}

type ToolCalledEvent struct {
	RunID       string
	ParentRunID string
	ToolCallID  string
	ToolName    string
	ArgsJSON    string
	CalledAt    time.Time
}

type ToolChoice struct {
	// Mode is "auto" (default), "required" (must use any tool), or "none" (no tools).
	Mode string `json:"mode,omitempty"`
	// ToolName forces use of a specific tool (when Mode is empty or "auto").
	ToolName string `json:"tool_name,omitempty"`
}

type ToolDefinition struct {
	Name              string   `json:"name"`
	Description       string   `json:"description,omitempty"`
	ParametersSchema  Schema   `json:"parameters_schema"`
	Kind              ToolKind `json:"kind"`
	Strict            *bool    `json:"strict,omitempty"`
	Sequential        bool     `json:"sequential,omitempty"`
	OuterTypedDictKey string   `json:"outer_typed_dict_key,omitempty"`
}

type ToolHandler func(ctx context.Context, rc *RunContext, argsJSON string) (any, error)

type ToolKind string

type ToolOption func(*toolConfig)

type ToolPrepareFunc func(ctx context.Context, rc *RunContext, def ToolDefinition) *ToolDefinition

type ToolResultValidatorFunc func(ctx context.Context, rc *RunContext, toolName string, result string) error

type ToolResultWithImages struct {
	Text   string
	Images []ImagePart
}

type ToolReturnPart struct {
	ToolName   string
	Content    any // string or structured data (serialized to JSON)
	ToolCallID string
	Timestamp  time.Time
	Images     []ImagePart // optional images to include in tool result
}

type Toolset struct {
	Name                 string
	Tools                []Tool
	Hooks                []Hook
	DynamicSystemPrompts []SystemPromptFunc
}

type TraceExporter interface {
	Export(ctx context.Context, trace *RunTrace) error
}

type TraceStep struct {
	Kind      TraceStepKind `json:"kind"`
	Timestamp time.Time     `json:"timestamp"`
	Duration  time.Duration `json:"duration"`
	Data      any           `json:"data"`
}

type TraceStepKind string

type TruncationConfig struct {
	// MaxTokens is the maximum estimated tokens per tool output.
	// Content exceeding this budget is truncated with a head/tail strategy.
	// Default: 16000 (~64KB of text).
	MaxTokens int
}

type TurnGuardrailFunc func(ctx context.Context, rc *RunContext, messages []ModelMessage) error

type TurnGuardrailRuntime struct {
	Name string
	Func TurnGuardrailFunc
}

type UnexpectedModelBehavior struct {
	Message string
	Body    string // raw response body, if available
}

type Usage struct {
	InputTokens      int            `json:"input_tokens,omitempty"`
	OutputTokens     int            `json:"output_tokens,omitempty"`
	CacheWriteTokens int            `json:"cache_write_tokens,omitempty"`
	CacheReadTokens  int            `json:"cache_read_tokens,omitempty"`
	Details          map[string]int `json:"details,omitempty"`
}

type UsageLimitExceeded struct {
	Message string
}

type UsageLimits struct {
	RequestLimit      *int
	InputTokensLimit  *int
	OutputTokensLimit *int
	TotalTokensLimit  *int
	ToolCallsLimit    *int // Maximum total tool calls per run.
}

type UsageQuota struct {
	MaxRequests     int // max model requests (0 = unlimited)
	MaxTotalTokens  int // max total tokens across all requests (0 = unlimited)
	MaxInputTokens  int // max input/prompt tokens (0 = unlimited)
	MaxOutputTokens int // max output/completion tokens (0 = unlimited)
}

type UserError struct {
	Message string
}

type UserPromptPart struct {
	Content   string
	Timestamp time.Time
}