tools

type AnnotatedTool interface {
	Tool
	// Annotations 返回工具安全注解
	Annotations() *ToolAnnotations
}

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

type BaseLongRunningTool struct {
	BaseTool
	// contains filtered or unexported fields
}

type BaseTool struct {
	ToolName        string // 导出字段
	ToolDescription string // 导出字段
}

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

type CacheConfig struct {
	// Enabled 是否启用缓存
	Enabled bool

	// Strategy 缓存策略
	Strategy CacheStrategy

	// TTL 缓存过期时间
	TTL time.Duration

	// CacheDir 文件缓存目录（仅用于 file 和 both 策略）
	CacheDir string

	// MaxMemoryItems 内存缓存最大条目数（0 表示无限制）
	MaxMemoryItems int

	// MaxFileSize 单个缓存文件最大大小（字节，0 表示无限制）
	MaxFileSize int64
}

type CacheEntry struct {
	Key       string
	Value     any
	CreatedAt time.Time
	ExpiresAt time.Time
	Size      int64
}

type CacheStats struct {
	Hits          int64
	Misses        int64
	Sets          int64
	Evictions     int64
	Errors        int64
	TotalSize     int64
	ItemCount     int64
	LastCleanupAt time.Time
}

type CacheStrategy string

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

type ConstraintType string

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

type Context interface {
	// Context 返回 Go 标准 context
	Context() context.Context

	// Value 获取上下文值
	Value(key any) any
}

type DefaultToolSelector struct{}

type DeferrableConfig struct {
	// DeferLoading 是否延迟加载，为 true 时工具不会预先加载到 LLM 上下文
	DeferLoading bool `json:"defer_loading"`

	// Category 工具分类，用于搜索过滤
	// 例如: "filesystem", "execution", "network", "mcp", "custom"
	Category string `json:"category,omitempty"`

	// Keywords 搜索关键词，用于 BM25 索引
	Keywords []string `json:"keywords,omitempty"`
}

type DeferrableTool interface {
	Tool
	// DeferConfig 返回延迟加载配置
	DeferConfig() *DeferrableConfig
}

type EnhancedContext interface {
	Context // 继承基础接口

	// CallID 工具调用的唯一标识符
	CallID() string

	// AgentID 当前 Agent ID
	AgentID() string

	// SessionID 当前会话 ID
	SessionID() string

	// InvocationID 当前调用 ID
	InvocationID() string

	// State 访问会话状态
	State() session.State

	// Actions 获取事件动作
	Actions() *session.EventActions

	// SearchMemory 搜索 Agent 记忆
	SearchMemory(ctx context.Context, query string) ([]MemoryResult, error)

	// GetArtifact 获取 Artifact
	GetArtifact(ctx context.Context, name string) (any, error)

	// SaveArtifact 保存 Artifact
	SaveArtifact(ctx context.Context, name string, data any) error

	// EmitEvent 发送自定义事件
	EmitEvent(event *types.Event) error

	// Logger 获取日志记录器
	Logger() Logger

	// Tracer 获取追踪器
	Tracer() Tracer

	// Metrics 获取指标收集器
	Metrics() Metrics
}

type EnhancedTool interface {
	Tool // 继承基础接口

	// IsLongRunning 是否为长时运行工具
	// 长时运行工具会先返回资源 ID，稍后完成操作
	IsLongRunning() bool

	// Timeout 工具执行超时时间
	// 返回 0 表示使用默认超时
	Timeout() time.Duration

	// RequiresApproval 是否需要人工审批
	RequiresApproval() bool

	// Priority 工具优先级 (用于并发控制)
	// 数值越大优先级越高
	Priority() int

	// RetryPolicy 重试策略
	RetryPolicy() *RetryPolicy

	// Metadata 工具元数据
	Metadata() map[string]any
}

type ExampleableTool interface {
	Tool
	// Examples 返回工具使用示例列表
	// 建议提供 1-5 个示例，涵盖常见使用场景
	Examples() []ToolExample
}

type ExecuteRequest struct {
	Tool    Tool
	Input   map[string]any
	Context *ToolContext
	Timeout time.Duration
}

type ExecuteResult struct {
	Success    bool
	Output     any
	Error      error
	DurationMs int64
	StartedAt  time.Time
	EndedAt    time.Time
}

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

type ExecutorConfig struct {
	MaxConcurrency int           // 最大并发数
	DefaultTimeout time.Duration // 默认超时时间
}

type Field struct {
	Key   string
	Value any
}

type Interruptible interface {
	Pause() error
	Resume() error
	Cancel() error
}

type Logger interface {
	Debug(msg string, fields ...Field)
	Info(msg string, fields ...Field)
	Warn(msg string, fields ...Field)
	Error(msg string, fields ...Field)
}

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

type LongRunningTool interface {
	Tool

	// IsLongRunning 标记为长时运行工具
	IsLongRunning() bool

	// StartAsync 异步启动工具执行
	// 返回任务 ID，可用于查询状态或取消
	StartAsync(ctx context.Context, args map[string]any) (string, error)

	// GetStatus 获取任务执行状态
	GetStatus(ctx context.Context, taskID string) (*TaskStatus, error)

	// Cancel 取消正在执行的任务
	Cancel(ctx context.Context, taskID string) error
}

type MCPManagerInterface interface {
	// ListServers 列出所有 MCP 服务器 ID
	ListServers() []string
	// GetServer 获取指定的 MCP 服务器
	GetServer(serverID string) (any, bool)
}

type MemoryResult struct {
	Content   string
	Score     float64
	Timestamp time.Time
	Metadata  map[string]any
}

type Metrics interface {
	IncrementCounter(name string, value int64)
	RecordDuration(name string, duration time.Duration)
}

type NoConstraints struct{}

type Predicate func(ctx ReadonlyContext, tool Tool) bool

type ReadonlyContext interface {
	AgentID() string
	SessionID() string
	State() session.ReadonlyState
}

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

type Reporter interface {
	Progress(progress float64, message string, step, total int, metadata map[string]any, etaMs int64)
	Intermediate(label string, data any)
}

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

type RetryPolicy struct {
	// MaxRetries 最大重试次数
	MaxRetries int

	// InitialBackoff 初始退避时间
	InitialBackoff time.Duration

	// MaxBackoff 最大退避时间
	MaxBackoff time.Duration

	// BackoffMultiplier 退避倍数
	BackoffMultiplier float64

	// RetryableErrors 可重试的错误类型
	RetryableErrors []string
}

type Span interface {
	End()
	SetAttribute(key string, value any)
	RecordError(err error)
}

type TaskState int

type TaskStatus struct {
	TaskID    string         // 任务 ID
	State     TaskState      // 当前状态
	Progress  float64        // 进度 0.0 - 1.0
	Result    any            // 执行结果（完成时）
	Error     error          // 错误信息（失败时）
	StartTime time.Time      // 开始时间
	EndTime   *time.Time     // 结束时间（完成/失败/取消时）
	Metadata  map[string]any // 额外元数据
}

type Tool interface {
	// Name 工具名称
	Name() string

	// Description 工具描述
	Description() string

	// InputSchema JSON Schema定义
	InputSchema() map[string]any

	// Execute 执行工具
	Execute(ctx context.Context, input map[string]any, tc *ToolContext) (any, error)

	// Prompt 工具使用说明(可选)
	Prompt() string
}

type ToolAnnotations struct {
	// ReadOnly 工具是否只读（不修改任何状态）
	// 只读工具在 SmartApprove 模式下可以自动批准
	ReadOnly bool `json:"read_only"`

	// Destructive 工具是否具有破坏性（可能导致数据丢失）
	// 破坏性工具在大多数模式下都需要用户确认
	Destructive bool `json:"destructive"`

	// Idempotent 工具是否幂等（多次执行结果相同）
	// 幂等工具更安全，可以重试
	Idempotent bool `json:"idempotent"`

	// OpenWorld 工具是否涉及外部系统（网络、第三方 API）
	// 涉及外部系统的工具即使只读也可能有安全风险
	OpenWorld bool `json:"open_world"`

	// RiskLevel 风险级别 (0-4)
	// 0: safe - 完全安全的只读操作
	// 1: low - 低风险，可逆操作
	// 2: medium - 中等风险，需要注意
	// 3: high - 高风险，可能导致数据丢失
	// 4: critical - 极高风险，可能导致不可逆损失
	RiskLevel int `json:"risk_level"`

	// Category 工具分类
	// 例如: "filesystem", "execution", "network", "database", "system"
	Category string `json:"category,omitempty"`

	// RequiresConfirmation 是否需要用户确认
	// 设为 true 时，无论权限模式如何都需要确认
	RequiresConfirmation bool `json:"requires_confirmation,omitempty"`
}

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

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

type ToolChoice struct {
	// Type 选择类型: "auto", "any", "tool"
	Type string `json:"type"`

	// Name 当 Type="tool" 时，指定工具名称
	Name string `json:"name,omitempty"`

	// DisableParallelToolUse 禁用并行工具调用
	DisableParallelToolUse bool `json:"disable_parallel_tool_use,omitempty"`
}

type ToolConfig struct {
	Name       string         `json:"name"`
	RegistryID string         `json:"registry_id,omitempty"`
	Config     map[string]any `json:"config,omitempty"`
}

type ToolConstraints interface {
	// IsAllowed 检查工具是否被允许使用
	IsAllowed(ctx context.Context, toolName string) bool

	// GetAllowedTools 获取所有允许的工具名称
	GetAllowedTools(ctx context.Context) []string

	// GetConstraintType 获取约束类型
	GetConstraintType() ConstraintType
}

type ToolContext struct {
	AgentID    string
	Sandbox    sandbox.Sandbox
	Signal     context.Context
	Reporter   Reporter
	Emit       func(eventType string, data any) // Deprecated: use Reporter
	Services   map[string]any
	ThreadID   string              // Working Memory 会话 ID
	ResourceID string              // Working Memory 资源 ID
	MCPManager MCPManagerInterface // MCP 管理器，用于访问 MCP 资源
}

type ToolExample struct {
	// Description 示例描述，说明这个示例演示的场景
	Description string `json:"description"`

	// Input 示例输入参数
	Input map[string]any `json:"input"`

	// Output 可选的预期输出，用于展示工具返回格式
	Output any `json:"output,omitempty"`
}

type ToolFactory func(config map[string]any) (Tool, error)

type ToolNotFoundError struct {
	Name string
}

type ToolSelector interface {
	// SelectTools 根据上下文选择工具
	SelectTools(ctx context.Context, allTools []Tool, constraints ToolConstraints) ([]Tool, error)

	// ShouldUseToolChoice 判断是否应该使用 tool_choice
	ShouldUseToolChoice(ctx context.Context, constraints ToolConstraints) (*ToolChoice, bool)
}

type Toolset interface {
	// Name 工具集名称
	Name() string

	// Description 工具集描述
	Description() string

	// Tools 返回工具列表
	// 可以根据上下文动态决定返回哪些工具
	Tools(ctx ReadonlyContext) ([]Tool, error)

	// Initialize 初始化工具集
	Initialize(ctx context.Context) error

	// Cleanup 清理工具集资源
	Cleanup(ctx context.Context) error
}

type Tracer interface {
	StartSpan(ctx context.Context, name string) (context.Context, Span)
}

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