tools

type AgentPermission struct {
	AgentID         string    `json:"agent_id"`
	AllowedTools    []string  `json:"allowed_tools,omitempty"` // Explicit allow list
	DeniedTools     []string  `json:"denied_tools,omitempty"`  // Explicit deny list
	InheritFrom     string    `json:"inherit_from,omitempty"`  // Parent agent ID
	MaxCallsPerHour int       `json:"max_calls_per_hour,omitempty"`
	CreatedAt       time.Time `json:"created_at"`
	UpdatedAt       time.Time `json:"updated_at"`
}

type ApprovalHandler interface {
	RequestApproval(ctx context.Context, permCtx *PermissionContext, rule *PermissionRule) (approvalID string, err error)
	CheckApprovalStatus(ctx context.Context, approvalID string) (approved bool, err error)
}

type AuditBackend interface {
	// Write 将审计条目写入后端。
	Write(ctx context.Context, entry *AuditEntry) error

	// Query 从后端检索审计条目.
	Query(ctx context.Context, filter *AuditFilter) ([]*AuditEntry, error)

	// Close 关闭后端。
	Close() error
}

type AuditEntry struct {
	ID        string            `json:"id"`
	Timestamp time.Time         `json:"timestamp"`
	EventType AuditEventType    `json:"event_type"`
	AgentID   string            `json:"agent_id"`
	UserID    string            `json:"user_id"`
	SessionID string            `json:"session_id,omitempty"`
	TraceID   string            `json:"trace_id,omitempty"`
	ToolName  string            `json:"tool_name"`
	Arguments json.RawMessage   `json:"arguments,omitempty"`
	Result    json.RawMessage   `json:"result,omitempty"`
	Error     string            `json:"error,omitempty"`
	Duration  time.Duration     `json:"duration,omitempty"`
	Decision  string            `json:"decision,omitempty"` // For permission checks
	Cost      float64           `json:"cost,omitempty"`     // For cost tracking
	Metadata  map[string]string `json:"metadata,omitempty"`
	RequestIP string            `json:"request_ip,omitempty"`
}

type AuditEventType string

type AuditFilter struct {
	AgentID   string         `json:"agent_id,omitempty"`
	UserID    string         `json:"user_id,omitempty"`
	ToolName  string         `json:"tool_name,omitempty"`
	EventType AuditEventType `json:"event_type,omitempty"`
	StartTime *time.Time     `json:"start_time,omitempty"`
	EndTime   *time.Time     `json:"end_time,omitempty"`
	SessionID string         `json:"session_id,omitempty"`
	TraceID   string         `json:"trace_id,omitempty"`
	Limit     int            `json:"limit,omitempty"`
	Offset    int            `json:"offset,omitempty"`
}

type AuditLogger interface {
	// Log 同步记录一条审计条目。
	Log(ctx context.Context, entry *AuditEntry) error

	// LogAsync 异步记录审计条目.
	LogAsync(entry *AuditEntry)

	// Query 根据过滤器检索审计条目。
	Query(ctx context.Context, filter *AuditFilter) ([]*AuditEntry, error)

	// Close 关闭审计日志并刷新待写入条目。
	Close() error
}

type AuditLoggerConfig struct {
	Backends       []AuditBackend
	AsyncQueueSize int
	AsyncWorkers   int
	IDGenerator    func() string
}

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

type Budget struct {
	ID              string       `json:"id"`
	Name            string       `json:"name"`
	Description     string       `json:"description,omitempty"`
	Scope           BudgetScope  `json:"scope"`
	ScopeID         string       `json:"scope_id,omitempty"` // Agent ID, User ID, etc.
	Limit           float64      `json:"limit"`              // Budget limit
	Unit            CostUnit     `json:"unit"`
	Period          BudgetPeriod `json:"period"`
	AlertThresholds []float64    `json:"alert_thresholds,omitempty"` // Percentages (e.g., 50, 80, 100)
	Enabled         bool         `json:"enabled"`
	CreatedAt       time.Time    `json:"created_at"`
	UpdatedAt       time.Time    `json:"updated_at"`
}

type BudgetPeriod string

type BudgetScope string

type CostAlert struct {
	ID         string         `json:"id"`
	Timestamp  time.Time      `json:"timestamp"`
	Level      CostAlertLevel `json:"level"`
	BudgetID   string         `json:"budget_id"`
	Message    string         `json:"message"`
	Current    float64        `json:"current"`
	Limit      float64        `json:"limit"`
	Percentage float64        `json:"percentage"`
}

type CostAlertHandler interface {
	HandleAlert(ctx context.Context, alert *CostAlert) error
}

type CostAlertLevel string

type CostCheckResult struct {
	Allowed      bool       `json:"allowed"`
	Cost         float64    `json:"cost"`
	Budget       *Budget    `json:"budget,omitempty"`
	CurrentUsage float64    `json:"current_usage"`
	Remaining    float64    `json:"remaining"`
	Alert        *CostAlert `json:"alert,omitempty"`
	Reason       string     `json:"reason,omitempty"`
}

type CostController interface {
	// CalculateCost 计算工具调用的成本。
	CalculateCost(toolName string, args json.RawMessage) (float64, error)

	// CheckBudget 检查是否在预算范围内。
	CheckBudget(ctx context.Context, agentID, userID, sessionID, toolName string, cost float64) (*CostCheckResult, error)

	// RecordCost 记录成本。
	RecordCost(record *CostRecord) error

	// SetToolCost 设置工具的成本配置。
	SetToolCost(cost *ToolCost) error

	// GetToolCost 获取工具的成本配置.
	GetToolCost(toolName string) (*ToolCost, bool)

	// AddBudget 添加预算。
	AddBudget(budget *Budget) error

	// RemoveBudget 删除预算。
	RemoveBudget(budgetID string) error

	// GetBudget 根据 ID 获取预算.
	GetBudget(budgetID string) (*Budget, bool)

	// ListBudgets 列出所有预算.
	ListBudgets() []*Budget

	// GetUsage 获取指定作用域的当前用量。
	GetUsage(scope BudgetScope, scopeID string, period BudgetPeriod) float64

	// GetOptimizations 获取成本优化建议.
	GetOptimizations(agentID, userID string) []*CostOptimization

	// GetCostReport 生成成本报告。
	GetCostReport(filter *CostReportFilter) (*CostReport, error)
}

type CostOptimization struct {
	Type        string  `json:"type"`
	Description string  `json:"description"`
	Savings     float64 `json:"savings,omitempty"`
	Priority    int     `json:"priority"`
}

type CostRecord struct {
	ID        string            `json:"id"`
	Timestamp time.Time         `json:"timestamp"`
	AgentID   string            `json:"agent_id"`
	UserID    string            `json:"user_id"`
	SessionID string            `json:"session_id,omitempty"`
	ToolName  string            `json:"tool_name"`
	Cost      float64           `json:"cost"`
	Unit      CostUnit          `json:"unit"`
	Metadata  map[string]string `json:"metadata,omitempty"`
}

type CostReport struct {
	TotalCost   float64            `json:"total_cost"`
	TotalCalls  int64              `json:"total_calls"`
	AverageCost float64            `json:"average_cost"`
	ByTool      map[string]float64 `json:"by_tool,omitempty"`
	ByAgent     map[string]float64 `json:"by_agent,omitempty"`
	ByUser      map[string]float64 `json:"by_user,omitempty"`
	ByDay       map[string]float64 `json:"by_day,omitempty"`
	TopTools    []ToolCostSummary  `json:"top_tools,omitempty"`
	GeneratedAt time.Time          `json:"generated_at"`
}

type CostReportFilter struct {
	AgentID   string     `json:"agent_id,omitempty"`
	UserID    string     `json:"user_id,omitempty"`
	ToolName  string     `json:"tool_name,omitempty"`
	StartTime *time.Time `json:"start_time,omitempty"`
	EndTime   *time.Time `json:"end_time,omitempty"`
	GroupBy   string     `json:"group_by,omitempty"` // agent, user, tool, day, hour
}

type CostUnit string

type DatabaseAuditBackend interface {
	AuditBackend
	// Migrate 创建或更新数据库表结构。
	Migrate(ctx context.Context) error
}

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

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

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

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

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

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

type DegradeHandler interface {
	GetDegradedResponse(ctx context.Context, rlCtx *RateLimitContext) (json.RawMessage, error)
}

type FallbackConfig struct {
	MaxRetries      int               `json:"max_retries"`
	RetryDelayMs    int               `json:"retry_delay_ms"`
	Alternates      map[string]string `json:"alternates"`     // 工具名 -> 备用工具名
	SkipOnErrors    []string          `json:"skip_on_errors"` // 遇到这些错误时跳过
	DefaultStrategy FallbackStrategy  `json:"default_strategy"`
}

type FallbackStrategy string

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

type FileAuditBackendConfig struct {
	Directory   string
	MaxFileSize int64 // Max file size in bytes before rotation
}

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

type LLMCallInfo struct {
	Request  llm.ChatRequest  `json:"request"`
	Response llm.ChatResponse `json:"response"`
}

type Limiter interface {
	Allow() bool
	Remaining() int
	ResetAt() time.Time
	Reset()
}

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

type ParallelConfig struct {
	MaxConcurrency   int           // Maximum concurrent tool executions (0 = unlimited)
	ExecutionTimeout time.Duration // Global timeout for all parallel executions
	FailFast         bool          // Stop all executions on first error
	RetryOnError     bool          // Retry failed tool calls
	MaxRetries       int           // Maximum retry attempts per tool
	RetryDelay       time.Duration // Delay between retries
	CollectPartial   bool          // Return partial results on timeout/cancel
	DependencyGraph  bool          // Enable dependency-aware execution order
}

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

type ParallelResult struct {
	Results       []ToolResult  `json:"results"`
	TotalDuration time.Duration `json:"total_duration"`
	Completed     int           `json:"completed"`
	Failed        int           `json:"failed"`
	Cancelled     int           `json:"cancelled"`
	PartialResult bool          `json:"partial_result"`
}

type PermissionCheckResult struct {
	Decision     PermissionDecision `json:"decision"`
	MatchedRule  *PermissionRule    `json:"matched_rule,omitempty"`
	Reason       string             `json:"reason"`
	ApprovalID   string             `json:"approval_id,omitempty"` // For require_approval decisions
	CheckedAt    time.Time          `json:"checked_at"`
	CheckLatency time.Duration      `json:"check_latency"`
}

type PermissionContext struct {
	AgentID   string            `json:"agent_id"`
	UserID    string            `json:"user_id"`
	Roles     []string          `json:"roles"`
	ToolName  string            `json:"tool_name"`
	Arguments map[string]any    `json:"arguments,omitempty"`
	Metadata  map[string]string `json:"metadata,omitempty"`
	RequestIP string            `json:"request_ip,omitempty"`
	RequestAt time.Time         `json:"request_at"`
	TraceID   string            `json:"trace_id,omitempty"`
	SessionID string            `json:"session_id,omitempty"`
}

type PermissionDecision string

type PermissionManager interface {
	// 检查是否允许调用工具 。
	CheckPermission(ctx context.Context, permCtx *PermissionContext) (*PermissionCheckResult, error)

	// 添加规则添加了权限规则 。
	AddRule(rule *PermissionRule) error

	// 删除规则删除权限规则 。
	RemoveRule(ruleID string) error

	// Get Rule 以 ID 检索许可规则 。
	GetRule(ruleID string) (*PermissionRule, bool)

	// List Rules 列出所有许可规则 。
	ListRules() []*PermissionRule

	// 添加Role增加了一个角色.
	AddRole(role *Role) error

	// 删除 Role 删除一个角色 。
	RemoveRole(roleID string) error

	// GetRole通过ID检索角色.
	GetRole(roleID string) (*Role, bool)

	// AssignRoleToUser为用户分配一个角色.
	AssignRoleToUser(userID, roleID string) error

	// GetUserRoles为用户获得所有角色.
	GetUserRoles(userID string) []string

	// Set AgentPermission 设置特定代理权限.
	SetAgentPermission(perm *AgentPermission) error

	// Get AgentPermission获得特定代理权限.
	GetAgentPermission(agentID string) (*AgentPermission, bool)
}

type PermissionRule struct {
	ID          string             `json:"id"`
	Name        string             `json:"name"`
	Description string             `json:"description,omitempty"`
	ToolPattern string             `json:"tool_pattern"`          // Tool name pattern (supports wildcards)
	Decision    PermissionDecision `json:"decision"`              // allow/deny/require_approval
	Priority    int                `json:"priority"`              // Higher priority rules are evaluated first
	Conditions  []RuleCondition    `json:"conditions,omitempty"`  // Additional conditions
	ValidFrom   *time.Time         `json:"valid_from,omitempty"`  // Permission start time
	ValidUntil  *time.Time         `json:"valid_until,omitempty"` // Permission expiry time
	CreatedAt   time.Time          `json:"created_at"`
	UpdatedAt   time.Time          `json:"updated_at"`
}

type QueueHandler interface {
	Enqueue(ctx context.Context, rlCtx *RateLimitContext) error
	Dequeue(ctx context.Context) (*RateLimitContext, error)
}

type RateLimitAction string

type RateLimitConfig struct {
	MaxCalls int           // Maximum calls
	Window   time.Duration // Time window
}

type RateLimitContext struct {
	AgentID   string    `json:"agent_id"`
	UserID    string    `json:"user_id"`
	SessionID string    `json:"session_id,omitempty"`
	ToolName  string    `json:"tool_name"`
	RequestAt time.Time `json:"request_at"`
}

type RateLimitManager interface {
	// CheckRateLimit 检查请求是否被允许。
	CheckRateLimit(ctx context.Context, rlCtx *RateLimitContext) (*RateLimitResult, error)

	// AddRule 添加速率限制规则。
	AddRule(rule *RateLimitRule) error

	// RemoveRule 删除速率限制规则。
	RemoveRule(ruleID string) error

	// GetRule 根据 ID 检索速率限制规则。
	GetRule(ruleID string) (*RateLimitRule, bool)

	// ListRules 列出所有速率限制规则。
	ListRules() []*RateLimitRule

	// GetStats 返回速率限制统计信息.
	GetStats(scope RateLimitScope, key string) *RateLimitStats

	// Reset 重置指定 key 的速率限制计数器。
	Reset(scope RateLimitScope, key string) error
}

type RateLimitResult struct {
	Allowed        bool            `json:"allowed"`
	Rule           *RateLimitRule  `json:"rule,omitempty"`
	Action         RateLimitAction `json:"action,omitempty"`
	RetryAfter     time.Duration   `json:"retry_after,omitempty"`
	RemainingCalls int             `json:"remaining_calls"`
	ResetAt        time.Time       `json:"reset_at,omitempty"`
	Reason         string          `json:"reason,omitempty"`
}

type RateLimitRule struct {
	ID          string            `json:"id"`
	Name        string            `json:"name"`
	Description string            `json:"description,omitempty"`
	Scope       RateLimitScope    `json:"scope"`
	Strategy    RateLimitStrategy `json:"strategy"`
	ToolPattern string            `json:"tool_pattern,omitempty"` // For tool-specific limits
	MaxRequests int               `json:"max_requests"`           // Maximum requests allowed
	Window      time.Duration     `json:"window"`                 // Time window
	BurstSize   int               `json:"burst_size,omitempty"`   // For token bucket
	RefillRate  float64           `json:"refill_rate,omitempty"`  // Tokens per second for token bucket
	Action      RateLimitAction   `json:"action"`                 // Action when limit exceeded
	Priority    int               `json:"priority"`               // Higher priority rules are checked first
	Enabled     bool              `json:"enabled"`
	CreatedAt   time.Time         `json:"created_at"`
	UpdatedAt   time.Time         `json:"updated_at"`
}

type RateLimitScope string

type RateLimitStats struct {
	Scope            RateLimitScope `json:"scope"`
	Key              string         `json:"key"`
	TotalRequests    int64          `json:"total_requests"`
	AllowedRequests  int64          `json:"allowed_requests"`
	RejectedRequests int64          `json:"rejected_requests"`
	CurrentCount     int            `json:"current_count"`
	WindowStart      time.Time      `json:"window_start"`
	WindowEnd        time.Time      `json:"window_end"`
}

type RateLimitStrategy string

type ReActConfig struct {
	MaxIterations int  // Maximum iterations (prevents infinite loops)
	StopOnError   bool // Stop on tool execution error
}

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

type ReActStep struct {
	StepNumber   int            `json:"step_number"`
	Thought      string         `json:"thought,omitempty"`
	Actions      []llm.ToolCall `json:"actions,omitempty"`
	Observations []ToolResult   `json:"observations,omitempty"`
	Timestamp    string         `json:"timestamp"`
	TokensUsed   int            `json:"tokens_used,omitempty"`
}

type ReActStreamEvent struct {
	Type          string            `json:"type"`
	Iteration     int               `json:"iteration,omitempty"`
	Chunk         *llm.StreamChunk  `json:"chunk,omitempty"`
	ToolCalls     []llm.ToolCall    `json:"tool_calls,omitempty"`
	ToolResults   []ToolResult      `json:"tool_results,omitempty"`
	FinalResponse *llm.ChatResponse `json:"final_response,omitempty"`
	Error         string            `json:"error,omitempty"`
}

type ReActTrace struct {
	TraceID      string      `json:"trace_id"`
	Steps        []ReActStep `json:"steps"`
	TotalTokens  int         `json:"total_tokens"`
	TotalSteps   int         `json:"total_steps"`
	Success      bool        `json:"success"`
	FinalAnswer  string      `json:"final_answer,omitempty"`
	ErrorMessage string      `json:"error_message,omitempty"`
}

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

type Role struct {
	ID          string    `json:"id"`
	Name        string    `json:"name"`
	Description string    `json:"description,omitempty"`
	ParentRoles []string  `json:"parent_roles,omitempty"` // For role inheritance
	Permissions []string  `json:"permissions,omitempty"`  // Permission rule IDs
	CreatedAt   time.Time `json:"created_at"`
	UpdatedAt   time.Time `json:"updated_at"`
}

type RuleCondition struct {
	Type     string `json:"type"`     // time_range, ip_range, parameter_check, etc.
	Operator string `json:"operator"` // eq, ne, gt, lt, contains, matches
	Field    string `json:"field"`    // Field to check
	Value    string `json:"value"`    // Expected value
}

type ScrapedImage struct {
	Alt string `json:"alt"`
	URL string `json:"url"`
}

type ScrapedLink struct {
	Text string `json:"text"`
	URL  string `json:"url"`
}

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

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

type TokenCounter interface {
	CountTokens(text string) (int, error)
}

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

type ToolCallWithDeps struct {
	Call         llmpkg.ToolCall                                     `json:"call"`
	DependsOn    []string                                            `json:"depends_on,omitempty"` // IDs of tool calls that must complete first
	ResultMapper func(results map[string]ToolResult) json.RawMessage `json:"-"`                    // Optional: modify args based on deps
}

type ToolCost struct {
	ToolName    string   `json:"tool_name"`
	BaseCost    float64  `json:"base_cost"`     // Base cost per call
	CostPerUnit float64  `json:"cost_per_unit"` // Cost per unit (e.g., per token)
	Unit        CostUnit `json:"unit"`          // Cost unit
	Description string   `json:"description,omitempty"`
}

type ToolCostSummary struct {
	ToolName  string  `json:"tool_name"`
	TotalCost float64 `json:"total_cost"`
	CallCount int64   `json:"call_count"`
	AvgCost   float64 `json:"avg_cost"`
}

type ToolExecutor interface {
	Execute(ctx context.Context, calls []llm.ToolCall) []ToolResult
	ExecuteOne(ctx context.Context, call llm.ToolCall) ToolResult
}

type ToolFunc func(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

type ToolMetadata struct {
	Schema      llm.ToolSchema   // Tool JSON Schema
	Permission  string           // Required permission (optional)
	RateLimit   *RateLimitConfig // Rate limit config (optional)
	Timeout     time.Duration    // Execution timeout (default 30s)
	Description string           // Detailed description
}

type ToolRegistry interface {
	Register(name string, fn ToolFunc, metadata ToolMetadata) error
	Unregister(name string) error
	Get(name string) (ToolFunc, ToolMetadata, error)
	List() []llm.ToolSchema
	Has(name string) bool
}

type ToolResult struct {
	ToolCallID string          `json:"tool_call_id"`
	Name       string          `json:"name"`
	Result     json.RawMessage `json:"result"`
	Error      string          `json:"error,omitempty"`
	Duration   time.Duration   `json:"duration"`
}

type WebScrapeOptions struct {
	Format           string   `json:"format"`                      // Output format: "markdown", "text", "html"
	IncludeLinks     bool     `json:"include_links,omitempty"`     // Include hyperlinks in output
	IncludeImages    bool     `json:"include_images,omitempty"`    // Include image descriptions
	MaxLength        int      `json:"max_length,omitempty"`        // Maximum content length in characters
	WaitForJS        bool     `json:"wait_for_js,omitempty"`       // Wait for JavaScript rendering
	Selectors        []string `json:"selectors,omitempty"`         // CSS selectors to extract specific elements
	ExcludeSelectors []string `json:"exclude_selectors,omitempty"` // CSS selectors to exclude
}

type WebScrapeProvider interface {
	// Scrape 从 URL 获取并提取内容 。
	Scrape(ctx context.Context, url string, opts WebScrapeOptions) (*WebScrapeResult, error)
	// 名称返回提供者名称 。
	Name() string
}

type WebScrapeResult struct {
	URL       string         `json:"url"`
	Title     string         `json:"title"`
	Content   string         `json:"content"`
	Format    string         `json:"format"`
	WordCount int            `json:"word_count"`
	Links     []ScrapedLink  `json:"links,omitempty"`
	Images    []ScrapedImage `json:"images,omitempty"`
	Metadata  map[string]any `json:"metadata,omitempty"`
	ScrapedAt time.Time      `json:"scraped_at"`
}

type WebScrapeToolConfig struct {
	Provider    WebScrapeProvider // Scraping backend provider
	DefaultOpts WebScrapeOptions  // Default scrape options
	Timeout     time.Duration     // Per-scrape timeout
	RateLimit   *RateLimitConfig  // Rate limiting
}

type WebSearchOptions struct {
	MaxResults     int      `json:"max_results"`               // Maximum number of results (default: 10)
	Language       string   `json:"language,omitempty"`        // Language code (e.g., "en", "zh")
	Region         string   `json:"region,omitempty"`          // Region code (e.g., "us", "cn")
	SafeSearch     bool     `json:"safe_search,omitempty"`     // Enable safe search filtering
	TimeRange      string   `json:"time_range,omitempty"`      // Time range: "day", "week", "month", "year"
	Domains        []string `json:"domains,omitempty"`         // Restrict to specific domains
	ExcludeDomains []string `json:"exclude_domains,omitempty"` // Exclude specific domains
}

type WebSearchProvider interface {
	// 搜索进行网络搜索并返回结果 。
	Search(ctx context.Context, query string, opts WebSearchOptions) ([]WebSearchResult, error)
	// 名称返回提供者名称 。
	Name() string
}

type WebSearchResult struct {
	Title       string         `json:"title"`
	URL         string         `json:"url"`
	Snippet     string         `json:"snippet"`
	Content     string         `json:"content,omitempty"`      // Full content if available
	PublishedAt string         `json:"published_at,omitempty"` // Publication date
	Score       float64        `json:"score,omitempty"`        // Relevance score (0-1)
	Metadata    map[string]any `json:"metadata,omitempty"`
}

type WebSearchToolConfig struct {
	Provider    WebSearchProvider // Search backend provider
	DefaultOpts WebSearchOptions  // Default search options
	Timeout     time.Duration     // Per-search timeout
	RateLimit   *RateLimitConfig  // Rate limiting
}