executor

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

type BaseToolOpt struct {
	Name        string
	Description string
}

type ClientMCPServers interface {
	// SetMCPServers 换掉一条客户端连接登记的 MCP 连接；传空表示移除。只由 Conversation 的 Run 调用，与读取可以并发。
	// 两条客户端连接登记同一个 server id 时，先登记的生效；换掉自己的登记不改变它的先后。
	SetMCPServers(clientID string, connections []mcpclient.Connection)
	// GetMCPTools 返回生效的客户端 MCP 工具，每个绑定自己的连接：没连上的等，最多等各自的启动超时，连不上的跳过并记 Warn。
	// 同 id 的 server 被先登记的挡掉时，每次读取记一条 Warn client mcp server skipped。
	GetMCPTools(ctx context.Context) ([]Tool, error)
	// GetMCPServers 返回生效的客户端 MCP 连接此刻的情况，还没连上的也立刻返回；重复 id 里被跳过的不在其中。
	GetMCPServers() []mcpclient.ConnectionInfo
}

type ExecutionEnvironment interface {
	// GetID 返回模型选择执行环境时使用的 ID。
	GetID() string
	// GetDescription 返回执行环境说明。
	GetDescription() string
	// GetWorkspace 返回环境的工作区；测试里没有文件系统的环境返回 nil。
	GetWorkspace() workspace.Workspace
	// GetTools 返回环境共享的内置工具，这些工具不带 Session 状态。
	GetTools() []Tool
	// GetMCPTools 返回 serverIDs 选中的 MCP 工具，每个绑定自己的连接：没连上的等，最多等启动超时；
	// 弱依赖连不上跳过并记 Warn，强依赖连不上返回错误。nil 表示全部，[] 表示不用。
	GetMCPTools(ctx context.Context, serverIDs defs.OptionalStringList) ([]Tool, error)
	// GetMCPServers 返回各 MCP 连接此刻的情况；还没连上的连接也立刻返回。
	GetMCPServers() []mcpclient.ConnectionInfo
	// Run 运行各 MCP 连接直到 ctx 结束，全部断开后返回 ctx.Err()；某个连接运行出错时返回它的错误，没有 MCP 连接时直接返回 nil。只能调用一次。
	Run(ctx context.Context) error
}

type ExecutionEnvironmentOpt struct {
	ID          string
	Description string
	Workspace   workspace.Workspace
	Tools       []Tool
	// MCPServers 由 Conversation 填入本对话 Agent 会用到的 server；只取 ExecutorIDs 里含本环境 ID 的，
	// NewExecutionEnvironment 按本环境的工作区为它们创建连接，Run 之后才开始连。
	MCPServers []*mcpclient.ServerDefinition
}

type ExecutionFinishedEvent struct {
	// Result 是这次调用的最终结果；工具不存在、参数错误、执行失败和取消都写在 Result.Error 里。
	// Result.Executor 由 ToolExecutor 填入实际执行环境的 ID；协作工具和客户端 MCP 工具为空。
	Result *defs.ToolResult
	// AgentsInstructions 是工具这次调用读到的目录规则，每条的 Executor 字段已填为实际执行环境的 ID。
	AgentsInstructions []*defs.AgentsInstruction
	// HookRuns 是 ToolExecutor 为这次调用触发的 PreToolUse、PostToolUse 要保存的运行记录，Pre 在前、Post 在后；
	// 没有触发 hook 或没有命中时为空。
	HookRuns []*defs.HookRun
}

type ExecutionHookRunEvent struct {
	Run *defs.HookRun
}

type ExecutionProgressEvent struct {
	CallID string              `json:"call_id"`
	Stream ExecutionStreamType `json:"stream"`
	// Content 是合法 JSON；terminal 是 JSON 字符串。
	Content json.RawMessage `json:"content"`
}

type ExecutionStreamType string

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

type Tool interface {
	// GetDefinition 返回工具定义的副本。
	GetDefinition() *defs.ToolDefinition
	// Execute 执行一次调用并返回结果；参数错误、执行失败和取消都写入 ToolResult.Error，返回值非 nil 且 CallID 与调用一致。
	// progress 由 ToolExecutor 持有并在 Execute 返回后关闭；工具只发送，不需要进度的工具忽略它。
	Execute(ctx context.Context, call *defs.Item, progress chan<- *ExecutionProgressEvent) *ToolExecutionResult
}

type ToolExecutionResult struct {
	// Result 是交给模型的工具结果。
	Result *defs.ToolResult
	// AgentsInstructions 是这次调用读到的目录 AGENTS.md，例如 read_file 读到的文件所在目录的规则。
	AgentsInstructions []*defs.AgentsInstruction
}

type ToolExecutor interface {
	// GetTools 建出本轮工具表并存下，返回交给模型的工具定义；多个环境提供的工具带 executor 参数。返回内容由调用方持有。
	GetTools(ctx context.Context) ([]*defs.ToolDefinition, error)
	// Run 并发执行本批调用，按完成顺序发送 *ExecutionProgressEvent、*ExecutionHookRunEvent 与每个调用一次 *ExecutionFinishedEvent，
	// 全部结束后关闭 events。调用方读取 events 到关闭；调用 Item 克隆后才交给工具。
	Run(ctx context.Context, calls []*defs.Item, events chan<- ExecutorEvent)
}

type ToolExecutorOpt struct {
	// Environments 是能用的执行环境，第一个是默认环境；由 Conversation 持有，ToolExecutor 只借用。
	Environments []ExecutionEnvironment
	// SessionTools 是本 Session 为各环境构造的工具，键是环境 ID；和环境自带的工具一样参与 ToolNames 过滤、executor 参数和 hook。
	SessionTools map[string][]Tool
	// AgentTools 是协作工具，不带 executor 参数，不受 ToolNames 过滤。
	AgentTools []Tool
	// ClientMCPServers 提供客户端登记的 MCP 工具；nil 表示没有。只在 MCPServerIDs 为 nil 时使用，与其他工具重名时让位。
	ClientMCPServers ClientMCPServers
	// ToolNames 是内置工具和 Session 工具的可用名单；为空时全部可用。MCP 工具不受它过滤。
	ToolNames []string
	// MCPServerIDs 是可用的 MCP server；nil 表示全部，[] 表示不用。
	MCPServerIDs defs.OptionalStringList
	// Hooks 触发 PreToolUse、PostToolUse；nil 表示没有。没有环境时不触发。
	Hooks hook.Hooks
	// Session 是调用所在的 Session，随 hook 事件交给脚本。
	Session defs.Session
}