conversation

type ClientMCPServer struct {
	// ID 是这个 MCP server 的 ID，工具名里也用它。
	ID string
	// Transport 把请求转发给客户端那边的 MCP server。
	Transport mcp.Transport
}

type Conversation interface {
	// GetID 返回对话 ID。
	GetID() defs.ConversationID
	// GetRootSessionID 返回根 Session ID。
	GetRootSessionID() defs.SessionID
	// GetSkills 返回根 Agent 可用的 Skill 信息。
	GetSkills() []skill.SkillInfo
	// GetMCPServers 按执行环境顺序返回各 MCP 连接的当前状态，客户端登记的排在最后；还在连接的也直接列出。
	GetMCPServers() []MCPServerInfo
	// Run 启动执行环境和根 Session，串行处理换配置和客户端 MCP 登记，等 Session、连接和工作区全部停止后关闭 events；只能调用一次。
	// events 为 nil 时不发事件，否则调用方要一直读到它关闭；返回根 Session 的错误或停止原因，调用时 ctx 已取消则只做清理并返回 ctx.Err()。
	Run(ctx context.Context, events chan<- ConversationEvent) error
	// HandleInput 向根 Session 提交输入并返回 ItemID，执行结果看 Turn 结束事件；先等根 Session 首次启动，对话已停止或正在换配置时返回错误。
	HandleInput(ctx context.Context, input *ConversationInput) (defs.ItemID, error)
	// InterruptTurn 请求取消根 Session 的活动 Turn，返回它的 ID，不等取消完成；先等根 Session 首次启动，根 Session 没在运行或空闲时返回空。
	InterruptTurn(ctx context.Context) (defs.TurnID, error)
	// SteerInput 将根 Session 的排队用户输入移入指定轮。
	SteerInput(ctx context.Context, itemID defs.ItemID, turnID defs.TurnID) error
	// InterruptTurnWithInput 将根 Session 的排队用户输入置顶并取消指定轮。
	InterruptTurnWithInput(ctx context.Context, turnID defs.TurnID, itemID defs.ItemID) error
	// WithdrawInput 取出根 Session 的完整待处理用户输入组。
	WithdrawInput(ctx context.Context, itemID defs.ItemID) ([]*defs.Item, error)
	// CompactContext 请求根 Session 压缩上下文并返回 TurnID，不等压缩完成；先等根 Session 首次启动，忙时返回 session.ErrSessionBusy，已停止时返回错误。
	CompactContext(ctx context.Context) (defs.TurnID, error)
	// IsTerminalBusy 运行中的根或子 Session 是否还有未结束的后台命令？
	IsTerminalBusy() bool
	// ListSessionInfos 按 SessionID 返回全部 Session 的记录、状态、已保存用量和所选模型窗口。
	ListSessionInfos(ctx context.Context) ([]SessionInfo, error)
	// GetSessionDetails 返回本对话中 Session 的模型、环境、Skill 和工具信息；Session 不属于本对话时返回错误。
	GetSessionDetails(ctx context.Context, sessionID defs.SessionID) (SessionDetails, error)
	// SetSessionModel 校验并保存模型和推理强度，通知运行中的 Session 从下个 Turn 起使用；已保存但通知失败时仍返回记录和错误。
	// 没指定强度时，原强度新模型也支持就保留，否则用新模型的默认强度。
	SetSessionModel(ctx context.Context, sessionID defs.SessionID, model defs.ModelSelection) (defs.Session, error)
	// GetExecutorSettings 返回当前配置的 Executor 设置，已补上 local 目录。
	GetExecutorSettings() defs.ExecutorSettings
	// SetExecutorSettings 按新设置装配配置，交给 Run 停掉旧 Session 和执行环境、重启根 Session，返回补上 local 目录的设置；客户端 MCP 登记保留。
	// 调用方要先确认没有执行中的 Turn；装配失败时旧配置不变，换上后根 Session 启动失败则停止对话并返回错误。
	SetExecutorSettings(ctx context.Context, settings defs.ExecutorSettings) (defs.ExecutorSettings, error)
	// SetDefinitions 按新定义和当前设置重新装配并替换配置，校验全部 Session 的 Agent 都在新定义里；临时对话不装配 Executor 和 Skill。
	SetDefinitions(ctx context.Context, definitions *ConversationDefinitions) error
	// SetClientMCPServers 替换指定客户端登记的全部 MCP server，空列表表示移除；等 Run 换完登记后返回，从下个 Turn 起生效。
	// 创建连接失败、对话已停止或调用方取消时返回错误。
	SetClientMCPServers(ctx context.Context, clientID string, servers []ClientMCPServer) error
}

type ConversationDefinitions struct {
	// Agents 是本对话可使用的全部 Agent 定义；每个 Session 按持久化的 AgentName 选择其中一项。
	Agents []*agent.AgentDefinition
	// Models 是模型目录；各 Agent 的默认模型和摘要模型必须在其中。
	Models []*defs.ModelDefinition
	// MCPServers 是全部 MCP server 定义；对话只给本对话 Agent 会用到的建连接。
	MCPServers []*mcpclient.ServerDefinition
	// Hooks 是本对话使用的 hook，nil 表示没有 hook。
	Hooks hook.Hooks
	// Executors 是全部 Executor 定义，按 local、builtin、配置的顺序；对话按自己的 Executor 设置从中选出可用的建执行环境。
	Executors []*defs.ExecutorDefinition
	// Skills 是所有对话共用的 skill；和项目目录、主目录里的 skill 同名时，项目目录的优先，其次是这里的，主目录的最后。
	Skills []*skill.Skill
}

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

type ConversationInput struct {
	// Mode 是提交方式，含义见 session.SessionInputMode。
	Mode session.SessionInputMode
	// From 是发送方，必须是用户或 Agent。
	From *defs.Address
	// Content 是消息内容，HandleInput 会复制一份。
	Content []*defs.Content
	// InputID 可选：根 Session 本次运行期内重复的 InputID 只接收一次。
	InputID defs.InputID
}

type ConversationOpt struct {
	Query    dao.Query
	Mutation dao.Mutation
	// Definitions 是建对话时的定义；之后由 SetDefinitions 整份替换。
	Definitions *ConversationDefinitions
	// Environment 是客户端的环境变量（格式同 os.Environ），只给 local 种类的 Executor 执行命令用；
	// nil 时继承 serve 进程的环境。它只存在内存里，重新装配时沿用。
	Environment []string
	// MaxImageBytes 交给每个执行环境的 read_file，必须大于 0。
	MaxImageBytes int
	// Ephemeral 是否为临时对话？临时对话没有 Executor 和 Skill，换定义时也不装配。
	Ephemeral bool
}

type ConversationReconfigured struct {
	// Models 是新配置的模型目录。
	Models map[defs.ModelRef]*defs.ModelDefinition
	// AgentDefaultModels 以 Agent 名为键，值是这个 Agent 的默认模型。
	AgentDefaultModels map[string]defs.ModelRef
	// ExecutorSettings 是新配置的 Executor 设置，已补上 local 目录。
	ExecutorSettings defs.ExecutorSettings
}

type ConversationSessionEvent struct {
	SessionID defs.SessionID
	Event     session.SessionEvent
}

type ConversationSessionStarted struct {
	Session defs.Session
	// LastSavedOrdinal 是启动前读到的这个 Session 日志的最新序号，之后写入的 Item 都以 SessionItemsSaved 到达。
	LastSavedOrdinal storage.Ordinal
}

type ConversationSessionStopped struct {
	SessionID defs.SessionID
	// Err 是 Session.Run 的返回值。
	Err error
}

type ExecutorDetails struct {
	ID                 string `json:"id"`
	Description        string `json:"description,omitempty"`
	WorkspaceDirectory string `json:"workspace_directory,omitempty"`
}

type ForkConversationRequest struct {
	// Source 是来源对话记录（已保存，可以已归档）。
	Source defs.Conversation
	// BeforeTurnID 非空时复制到这一轮之前，不含这一轮；回退重来时用。
	BeforeTurnID defs.TurnID
	// LastTurnID 非空时复制到这一轮，含这一轮。
	LastTurnID defs.TurnID
	// Model 是新根 Session 的模型；零值时照抄来源根 Session 的模型。
	Model defs.ModelSelection
	// ExecutorSettings 原样存进新对话。
	ExecutorSettings defs.ExecutorSettings
}

type MCPServerInfo struct {
	ExecutorID string `json:"executor_id"`
	mcpclient.ConnectionInfo
}

type SendMessageParam struct {
	SessionID defs.SessionID           `json:"session_id" jsonschema:"description=接收方 SessionID；仅允许自己的后代或直接父方,minLength=1"`
	Message   string                   `json:"message" jsonschema:"description=发送给接收方的任务、补充要求或信息,minLength=1"`
	Mode      session.SessionInputMode `` /* 221-byte string literal not displayed */
	// Model 和 ReasoningEffort 只能用于后代；任一非空时先替换接收方的模型选择，再提交输入。
	Model           string `` /* 202-byte string literal not displayed */
	ReasoningEffort string `` /* 194-byte string literal not displayed */
}

type SessionDetails struct {
	ConversationID defs.ConversationID `json:"conversation_id"`
	// Title 由 Runtime 按已保存的对话记录填写，GetSessionDetails 留空。
	Title   string       `json:"title"`
	Session defs.Session `json:"session"`
	// Model 是 Session 使用的模型定义（不含连接参数）；所选模型不在模型目录里时为空。
	Model *defs.ModelDefinition `json:"model"`
	// CompactModel 是压缩使用的模型，Agent 没有单独配置时与 Model 相同；Model 为空时它也为空。
	CompactModel *defs.ModelDefinition `json:"compact_model"`
	// Executors 按配置顺序，第一个是默认 Executor。
	Executors []ExecutorDetails `json:"executors"`
	// Skills 是这个 Agent 可用的 Skill 名。
	Skills []string `json:"skills"`
	// Tools 是模型可见的工具名，包括协作工具。
	Tools []string `json:"tools"`
}

type SessionHistoryParam struct {
	SessionID defs.SessionID  `json:"session_id" jsonschema:"description=要读取本地执行历史的后代 SessionID,minLength=1"`
	Cursor    storage.Ordinal `` /* 173-byte string literal not displayed */
	Limit     int             `` /* 143-byte string literal not displayed */
}

type SessionInfo struct {
	Session defs.Session `json:"session"`
	// Status 是查询时的状态；Session 没在运行时取最近保存的 Turn。
	Status session.SessionStatus `json:"status"`
	// Usage 是这个 Session 已保存的全部 Turn 的用量之和，不含正在运行的 Turn。
	Usage defs.TokenUsage `json:"usage"`
	// ContextWindow 是这个 Session 所选模型的上下文窗口，模型不在目录里时为 0。
	ContextWindow int `json:"context_window"`
}

type SpawnAgentParam struct {
	TaskName        string `json:"task_name" jsonschema:"description=用于识别子任务的简短名称,minLength=1"`
	Message         string `` /* 166-byte string literal not displayed */
	ForkTurns       string `` /* 254-byte string literal not displayed */
	AgentName       string `` /* 146-byte string literal not displayed */
	Model           string `` /* 219-byte string literal not displayed */
	ReasoningEffort string `` /* 161-byte string literal not displayed */
}

type WaitAgentParam struct {
	TimeoutSeconds int `` /* 281-byte string literal not displayed */
}

type WorkspaceDirectories struct {
	Directory   string   `json:"directory"`
	Directories []string `json:"directories"`
}