tools

type AsyncToolExecutor interface {
	Executor // Still implements the basic Executor interface

	// ExecuteAsync may return immediately with a pending status
	ExecuteAsync(descriptor *ToolDescriptor, args json.RawMessage) (*ToolExecutionResult, error)
}

type ChatMessage struct {
	Role               string     `json:"role"`
	Content            string     `json:"content"`
	ToolCalls          []ToolCall `json:"tool_calls,omitempty"`
	ToolCallResponseID string     `json:"tool_call_id,omitempty"` // For tool result messages
}

type ChatRequest struct {
	System      string        `json:"system"`
	Messages    []ChatMessage `json:"messages"`
	Temperature float32       `json:"temperature"`
	TopP        float32       `json:"top_p"`
	MaxTokens   int           `json:"max_tokens"`
	Seed        *int          `json:"seed,omitempty"`
}

type ChatResponse struct {
	Content   string        `json:"content"`
	TokensIn  int           `json:"tokens_in"`
	TokensOut int           `json:"tokens_out"`
	Latency   time.Duration `json:"latency"`
	Raw       []byte        `json:"raw,omitempty"`
	ToolCalls []ToolCall    `json:"tool_calls,omitempty"` // Tools called in this response
}

type Coercion struct {
	Path string      `json:"path"`
	From interface{} `json:"from"`
	To   interface{} `json:"to"`
}

type Executor interface {
	Execute(descriptor *ToolDescriptor, args json.RawMessage) (json.RawMessage, error)
	Name() string
}

type HTTPConfig struct {
	URL            string            `json:"url" yaml:"url"`
	Method         string            `json:"method" yaml:"method"`
	HeadersFromEnv []string          `json:"headers_from_env,omitempty" yaml:"headers_from_env,omitempty"`
	TimeoutMs      int               `json:"timeout_ms" yaml:"timeout_ms"`
	Redact         []string          `json:"redact,omitempty" yaml:"redact,omitempty"`
	Headers        map[string]string `json:"headers,omitempty" yaml:"headers,omitempty"`
}

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

type MockScriptedExecutor struct{}

type MockStaticExecutor struct{}

type PendingToolInfo struct {
	// Reason for pending (e.g., "requires_approval", "waiting_external_api")
	Reason string `json:"reason"`

	// Human-readable description
	Message string `json:"message"`

	// Tool details (for middleware to use in notifications)
	ToolName string          `json:"tool_name"`
	Args     json.RawMessage `json:"args"`

	// Optional: expiration, callback URL, etc.
	ExpiresAt   *time.Time `json:"expires_at,omitempty"`
	CallbackURL string     `json:"callback_url,omitempty"`

	// Arbitrary metadata for custom middleware
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

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

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

type ToolCall struct {
	Name string          `json:"name"`
	Args json.RawMessage `json:"args"`
	ID   string          `json:"id"` // Provider-specific call ID
}

type ToolConfig struct {
	APIVersion string            `yaml:"apiVersion"`
	Kind       string            `yaml:"kind"`
	Metadata   metav1.ObjectMeta `yaml:"metadata,omitempty"`
	Spec       ToolDescriptor    `yaml:"spec"`
}

type ToolData struct {
	FilePath string
	Data     []byte
}

type ToolDescriptor struct {
	Name         string          `json:"name" yaml:"name"`
	Description  string          `json:"description" yaml:"description"`
	InputSchema  json.RawMessage `json:"input_schema" yaml:"input_schema"`   // JSON Schema Draft-07
	OutputSchema json.RawMessage `json:"output_schema" yaml:"output_schema"` // JSON Schema Draft-07
	Mode         string          `json:"mode" yaml:"mode"`                   // "mock" | "live"
	TimeoutMs    int             `json:"timeout_ms" yaml:"timeout_ms"`
	MockResult   json.RawMessage `json:"mock_result,omitempty" yaml:"mock_result,omitempty"`     // Static mock data
	MockTemplate string          `json:"mock_template,omitempty" yaml:"mock_template,omitempty"` // Template for dynamic mocks
	HTTPConfig   *HTTPConfig     `json:"http,omitempty" yaml:"http,omitempty"`                   // Live HTTP configuration
}

type ToolExecutionResult struct {
	Status  ToolExecutionStatus `json:"status"`
	Content json.RawMessage     `json:"content,omitempty"`
	Error   string              `json:"error,omitempty"`

	// Present when Status == ToolStatusPending
	PendingInfo *PendingToolInfo `json:"pending_info,omitempty"`
}

type ToolExecutionStatus string

type ToolGuidance struct {
	Support   string `json:"support,omitempty"`
	Assistant string `json:"assistant,omitempty"`
	Generic   string `json:"generic,omitempty"`
}

type ToolPolicy struct {
	ToolChoice          string   `json:"tool_choice"` // "auto" | "required" | "none"
	MaxToolCallsPerTurn int      `json:"max_tool_calls_per_turn"`
	MaxTotalToolCalls   int      `json:"max_total_tool_calls"`
	Blocklist           []string `json:"blocklist,omitempty"`
}

type ToolRepository interface {
	LoadTool(name string) (*ToolDescriptor, error)
	ListTools() ([]string, error)
	SaveTool(descriptor *ToolDescriptor) error
}

type ToolResult struct {
	Name      string          `json:"name"`
	ID        string          `json:"id"` // Matches ToolCall.ID
	Result    json.RawMessage `json:"result"`
	LatencyMs int64           `json:"latency_ms"`
	Error     string          `json:"error,omitempty"`
}

type ToolStats struct {
	TotalCalls int            `json:"total_calls"`
	ByTool     map[string]int `json:"by_tool"`
}

type ToolSupport interface {
	// BuildTooling converts tool descriptors to provider-native format
	BuildTooling(descriptors []*ToolDescriptor) (interface{}, error)

	// ChatWithTools performs a chat request with tool support
	ChatWithTools(req ChatRequest, tools interface{}, toolChoice string) (ChatResponse, []ToolCall, error)

	// ContinueWithToolResults continues conversation with tool results
	ContinueWithToolResults(prior ChatResponse, results []ToolResult) (ChatResponse, []ToolCall, error)
}

type ValidationError struct {
	Type   string `json:"type"` // "args_invalid" | "result_invalid" | "policy_violation"
	Tool   string `json:"tool"`
	Detail string `json:"detail"`
	Path   string `json:"path,omitempty"`
}