common

type Agent interface {
	// Do stores the current user input, starts the agent loop asynchronously,
	// and returns the context UID and the step stream for this run. The stream is
	// closed when the run finishes, is interrupted, or stops with an error.
	Do(context.Context, *AgentDoArgs, ...model.Option) (ContextUID, streaming.Stream[*Step], error)

	// Steer queues one or more user messages for a conversation. Messages are
	// committed after the next complete non-final turn. A final answer discards
	// pending messages, and steering a finalized conversation returns an error.
	Steer(context.Context, *AgentSteerArgs) error
}

type AgentContext struct {
	context.Context
	// contains filtered or unexported fields
}

type AgentDoArgs struct {
	UserInput AgentUserInput
	// ContextUID is the unique identifier for a conversation.
	// If set, the agent will load its managed context to continue thinking.
	ContextUID ContextUID
	// SpecialRequirements will be appended to the system prompt and also used in final answer generation
	SpecialRequirements []string
	// Compress decides whether to compress the steps when context exceeds the limit
	Compress bool
	// CompressionOptions configures context compression for this run.
	CompressionOptions CompressionOptions
	// ContextMeta stores stateless context meta
	ContextMeta map[AgentDoMetaKey]any
	// the max step to run the agent
	MaxStep int
	// Callbacks contains the callbacks for the agent execution
	Callbacks *Callbacks
	// SkillUsageInstruction is the instruction to guide the agent on how to use skills
	SkillUsageInstruction string
	// PlanUsageInstruction guides the React agent on when to create a plan and how granular the plan should be.
	// It is only used when EnablePlanning is true.
	PlanUsageInstruction string
	// FinalAnswerStreamingFunc receives streamed final-answer chunks.
	FinalAnswerStreamingFunc FinalAnswerStreamFn
	// FinalAnswerWebhook sends the settled final answer payload to the configured URL after the final step is stored
	FinalAnswerWebhook *FinalAnswerWebhookConfig
	// EnablePlanning enables planning tools during execution so the agent can create and update a plan while completing the task.
	EnablePlanning bool
	// ToolExecutionOptions configures how the agent executes tools, it is only used when EnablePlanning is true.
	ToolExecutionOptions *ToolExecutionOptions
}

type AgentDoMetaKey string

type AgentSteerArgs struct {
	// ContextUID identifies the conversation whose pending inbox receives the
	// messages.
	ContextUID ContextUID
	// UserInputs are queued as separate user messages in the supplied order.
	UserInputs []AgentUserInput
}

type AgentUsage struct {
	PromptTokens     int
	CachedTokens     int
	CompletionTokens int
}

type AgentUserInput struct {
	Text   string
	Images []*schema.ContentBlock
}

type CallbackFn func(*AgentContext, *Step)

type Callbacks struct {
	BeforeToolExecution CallbackFn
	AfterToolExecution  CallbackFn
}

type CompressionOptions struct {
	// Strategy selects the compaction algorithm.
	Strategy CompressionStrategy
	// RecentMessages overrides the number of raw recent messages retained.
	RecentMessages int
}

type CompressionStrategy string

type ContextUID string

type DefaultTool struct {
	ToolName        string `json:"tool_name"`
	ToolDescription string `json:"tool_description"`
	// ToolParameters stores the JSON Schema for tool parameters (required by LLM APIs)
	// Must be in format: {"type": "object", "properties": {...}, "required": [...]}
	ToolParameters ToolParameters                                 `json:"tool_parameters"`
	F              func(*AgentContext, map[string]any) ToolResult `json:"-"`
}

type DefaultToolResult struct {
	Result string `json:"result"`
}

type FinalAnswerStreamFn func(context.Context, []byte) error

type FinalAnswerWebhookConfig struct {
	URL     string            `json:"url"`
	Headers map[string]string `json:"headers,omitempty"`
	Timeout time.Duration     `json:"timeout,omitempty"`
}

type FinalAnswerWebhookPayload struct {
	Event       string     `json:"event"`
	Agent       string     `json:"agent"`
	ContextUID  ContextUID `json:"context_uid"`
	UserInput   string     `json:"user_input"`
	FinalAnswer string     `json:"final_answer"`
	Steps       []*Step    `json:"steps,omitempty"`
	GeneratedAt time.Time  `json:"generated_at"`
}

type MCPTool struct {
	MCPClient       client.MCPClient
	ToolName        string
	ToolDescription string
	ToolParameters  map[string]any
}

type MultimodalToolResult struct {
	Text   string
	Images []*schema.ContentBlock
}

type Step struct {
	Thought            string                 `json:"thought"`
	Action             string                 `json:"action"`
	UseToolOrNot       bool                   `json:"use_tool_or_not"`
	ToolName           string                 `json:"tool_name"`
	ActionInputParam   map[string]any         `json:"action_input_param"`
	IsFinalAnswer      bool                   `json:"is_final_answer"`
	Observation        string                 `json:"observation"`
	ObservationImages  []*schema.ContentBlock `json:"-"`
	OptimizationAdvice *string                `json:"optimization_advice,omitempty"`
	IsCompressed       bool                   `json:"-"`
	// Usage is the total token usage associated with this step.
	Usage         *AgentUsage `json:"usage,omitempty"`
	ModelUsage    *AgentUsage `json:"model_usage,omitempty"`
	CallbackUsage *AgentUsage `json:"callback_usage,omitempty"`
}

type ThinkArgs struct {
	Interim               string
	UserInput             AgentUserInput
	Steps                 []*Step
	SpecialRequirements   []string
	Compress              bool
	SkillUsageInstruction string
	EnablePlanning        bool
}

type ThinkResult struct {
	NewStep                 *Step
	IsCompressed            bool
	Interim                 string
	CompressedPreviousSteps []*Step
	PromptTokens            int
	CompletionTokens        int
}

type Tool interface {
	Name() string
	Description() string
	// Must be constructed by NewToolParameters
	Parameters() ToolParameters
	String() string
	Execute(*AgentContext, map[string]any) ToolResult
}

type ToolExecutionOptions struct {
	EnableParallel bool
	MaxConcurrency int
}

type ToolParameters map[string]any

type ToolProperty struct {
	Name        string         `json:"name"`
	Type        string         `json:"type"` // JSON Schema type: string, integer, number, boolean, array, object
	Required    bool           `json:"required"`
	Description string         `json:"description,omitempty"`
	Items       *ToolProperty  `json:"items,omitempty"`      // for array
	Properties  []ToolProperty `json:"properties,omitempty"` // for object
}

type ToolResult interface {
	String() string
	// ImageParts returns image content parts from the tool result.
	// Returns nil if the result contains no images.
	ImageParts() []*schema.ContentBlock
}