runtimeclient

type Client interface {
	// Run 连接并保持连接直到 ctx 结束；返回前关闭 Events。只能调用一次。
	// 认证失败（ErrUnauthorized）与 initialize 被拒绝时返回错误，不再重连；其他断线按退避重连。
	Run(ctx context.Context) error
	// Events 是按发生顺序交付的事件；调用方需持续读取到关闭。
	Events() <-chan ClientEvent
	// Reconnect 跳过普通断线的退避等待；正在连接或已经连接时不额外拨号。
	Reconnect(ctx context.Context) (err error)
	// SubscribeRunningConversations 启用全局运行集合订阅及断线恢复；初始集合和错误经 Events 交付，重复调用合并。
	SubscribeRunningConversations(ctx context.Context) (err error)
	// GetRPCFrames 返回有界调试记录的独立副本，并允许下一次日志变化通知。
	GetRPCFrames(ctx context.Context) (frames []RPCFrame, err error)
	// ClearRPCFrames 清空记录和拥塞丢帧计数，保留暂停状态和递增序号。
	ClearRPCFrames(ctx context.Context) (err error)
	// SetRPCLogPaused 暂停或恢复采集；不停止业务连接和事件。
	SetRPCLogPaused(ctx context.Context, paused bool) (err error)

	// CreateConversation 新建对话；Model 为零值时使用 Agent 的默认模型。
	CreateConversation(ctx context.Context, request *CreateConversationRequest) (defs.Conversation, error)
	// ListModels 返回模型目录（不含连接参数）与 agentName 的默认模型；agentName 为空时不返回默认模型。
	ListModels(ctx context.Context, agentName string) (runtime.ModelList, error)
	// GetSkills 返回已有对话或草稿 Agent 的 Skill 补全目录；草稿按请求的 Executor 设置查。
	GetSkills(ctx context.Context, request *GetSkillsRequest) ([]skill.SkillInfo, error)
	// GetHooks 调 hook/list，返回 serve 当前配置的全部 hook，按配置顺序；没有 hook 时返回空。
	GetHooks(ctx context.Context) ([]*hook.HookInfo, error)
	// ResolveWorkspaceDirectory 调 executor/resolveDirectory，在 Executor 所在的机器上把用户写的目录解析成绝对路径并确认它是目录。
	ResolveWorkspaceDirectory(ctx context.Context, request *ResolveWorkspaceDirectoryRequest) (string, error)
	// GetWorkspaceDirectories 调 executor/listDirectories，返回解析后的目录及其普通直接子目录。
	GetWorkspaceDirectories(ctx context.Context, request *GetWorkspaceDirectoriesRequest) (directories *conversation.WorkspaceDirectories, err error)
	// ListAgents 调 agent/list，返回配置里的全部 Agent 名、说明和默认模型，按配置顺序。
	ListAgents(ctx context.Context) ([]runtime.AgentInfo, error)
	// ListExecutors 调 executor/list，返回全部 Executor 和它们的默认根目录。
	ListExecutors(ctx context.Context) ([]conversation.ExecutorDetails, error)
	// ListMCPServers 调 mcpServer/list，返回已打开的对话里各 Executor 上的 MCP 连接情况，读取不等待连接；
	// 没有连接时返回空；对话在 serve 里没打开时返回错误。
	ListMCPServers(ctx context.Context, conversationID defs.ConversationID) ([]conversation.MCPServerInfo, error)
	// SetClientMCPServers 调 conversation/setClientMCPServers，换掉本连接为已打开的对话登记的全部客户端 MCP server；serverIDs 为空表示全部移除。
	// server 在本机运行，serve 登记后经本连接请本机连接它们：Client 为每条转发流发出 ClientMCPConnectRequested、ClientMCPMessageReceived
	// 与 ClientMCPDisconnectRequested，调用方用 SendClientMCPMessage、SendClientMCPClosed 回复。登记只属于当前这条连接：
	// 连接断开后 serve 移除它，重连后需要重新登记。对话在 serve 里没打开时返回错误。
	SetClientMCPServers(ctx context.Context, conversationID defs.ConversationID, serverIDs []string) error
	// SendClientMCPMessage 发出 clientMCP/message 通知，把本机 MCP server 在 streamID 这条流上发来的一条完整 JSON-RPC 消息交给 serve；
	// 写出后返回，不等待 serve 处理。当前没有已连接的连接时立即返回 ErrConnectionLost，不等重连：转发流属于发出它的那条连接，
	// 连接断开后 serve 已结束它，重连后的新连接不认识旧的 streamID。
	// ctx 在写出过程中取消会关闭整条连接，所有转发流和请求随之中断重连；调用方应传会话级 ctx。
	SendClientMCPMessage(ctx context.Context, streamID string, message json.RawMessage) error
	// SendClientMCPClosed 发出 clientMCP/closed 通知，告知 serve streamID 这条流已结束：连不上本机 MCP server 或它退出了；
	// err 是失败原因，nil 表示正常结束。送达规则与 ctx 的要求同 SendClientMCPMessage。
	SendClientMCPClosed(ctx context.Context, streamID string, err error) error
	// OpenTerminal 调 terminal/open，在 Executor 上为本连接新开一个终端并返回它的 ID、实际 Executor 和起始目录。
	// 输出和结束分别经 Events 交付 TerminalOutput 与 TerminalExited；终端只属于当前这条连接，连接断开后 serve 结束它，重连后需要重新打开。
	// virtual Executor 不支持终端，返回错误。
	OpenTerminal(ctx context.Context, request *TerminalOpenRequest) (result *runtimeprotocol.TerminalOpenResult, err error)
	// CloseTerminal 调 terminal/close，结束终端进程；终端已经结束时成功。结束后 Events 交付 TerminalExited。
	CloseTerminal(ctx context.Context, terminalID string) (err error)
	// WriteTerminal 发出 terminal/input 通知，把键盘或粘贴的字节原样写进终端；写出后返回，不等待 serve 处理。
	// 当前没有已连接的连接时立即返回 ErrConnectionLost，不等重连。
	WriteTerminal(terminalID string, data []byte) (err error)
	// ResizeTerminal 发出 terminal/resize 通知，修改终端的行列数；送达规则同 WriteTerminal。
	ResizeTerminal(terminalID string, rows, cols uint16) (err error)
	// ListProviders 调 provider/list，返回 serve 配置里的全部 Provider（带 API key 原文）和模型配置的默认模型：models.default_model，
	// 没写时是排序后的第一个模型，没有模型时是零值；defaults 是同次加载的模型默认配置。Agent 自己写了 model 时，它新建对话用的不是这个默认模型。
	ListProviders(ctx context.Context) (providers []defs.ProviderConfig, defaultModel defs.ModelRef, defaults defs.ModelDefaults, err error)
	// SetProvider 调 provider/set，写入整份 Provider 并让 serve 重新加载配置；defaultModel 不是零值时同一次写入还把默认模型改成它。
	// 返回 Runtime 替换目录的结果，加载失败时 serve 的文件和 Runtime 都不变，错误是加载错误原文。
	SetProvider(ctx context.Context, provider defs.ProviderConfig, defaultModel defs.ModelRef) (runtime.SetDefinitionsResult, error)
	// DeleteProvider 调 provider/delete，删除 Provider 并让 serve 重新加载配置；返回值同 SetProvider。
	DeleteProvider(ctx context.Context, providerID string) (runtime.SetDefinitionsResult, error)
	// SetDefaultModel 调 config/setDefaultModel，改 serve 配置里的默认模型并重新加载配置；返回值同 SetProvider。
	SetDefaultModel(ctx context.Context, ref defs.ModelRef) (runtime.SetDefinitionsResult, error)
	// ReloadConfig 调 config/reload，让 serve 不改文件、重新加载整份配置；返回值同 SetProvider。
	ReloadConfig(ctx context.Context) (runtime.SetDefinitionsResult, error)
	// ListCatalogProviders 调 catalog/providers/list，返回模型目录里可选的模型服务；目录拿不到时返回错误。
	ListCatalogProviders(ctx context.Context) ([]defs.CatalogProvider, error)
	// ListCatalogModels 调 catalog/models/list，返回模型目录里一个服务的全部模型，key 是写进配置文件的模型 id。
	ListCatalogModels(ctx context.Context, catalogProviderID string) (map[string]*defs.ProviderModelConfig, error)
	// FetchProviderModels 调 provider/fetchModels，让 serve 从 Provider 的上游 /models 拉模型并补字段；上游请求失败时返回错误。
	FetchProviderModels(ctx context.Context, provider defs.ProviderConfig) (map[string]*defs.ProviderModelConfig, error)
	// GetContextUsage 返回对话内一个 Session 已有的上下文占用详情，不调用模型。
	GetContextUsage(ctx context.Context, conversationID defs.ConversationID, sessionID defs.SessionID) (runtime.SessionContextUsage, error)
	// GetSessionDetails 返回对话内一个 Session 的静态配置：所选模型与摘要模型、Executor、skills、工具名。
	GetSessionDetails(ctx context.Context, conversationID defs.ConversationID, sessionID defs.SessionID) (conversation.SessionDetails, error)
	// SetSessionModel 保存 Session 所选的模型与推理强度，从下一个 Turn 开始生效，返回保存后的记录；成功后服务端推送 session/statusUpdated。
	SetSessionModel(ctx context.Context, request *SetSessionModelRequest) (defs.Session, error)
	// ListConversations 返回一页对话记录：Archived 为 true 时只列归档的，否则只列没归档的；NextCursor 非零时可作为下一页的 Cursor。
	ListConversations(ctx context.Context, request *ListConversationsRequest) (ListConversationsResult, error)
	// ForkConversation 调 conversation/fork，把对话复制到截取点为止并在服务端打开新对话，返回新对话的记录；原对话不变。
	// 截取点之前一轮都没有时服务端新建一个空对话。两个截取点都给、轮次不在根 Session 里、LastTurnID 还没结束时，分别返回可用
	// errors.Is 识别的 conversation.ErrForkBoundaryConflict、ErrForkTurnNotFound、ErrForkTurnRunning。
	ForkConversation(ctx context.Context, request *ForkConversationRequest) (defs.Conversation, error)
	// SetConversationArchived 调 conversation/setArchived，归档或取消归档，返回保存后的记录；不打开也不停止对话，
	// 已经是这个状态时什么都不改。
	SetConversationArchived(ctx context.Context, request *SetConversationArchivedRequest) (defs.Conversation, error)
	// DeleteConversation 调 conversation/delete，删除对话、全部 Session 和历史；有 Session 在执行 Turn 时返回可用 errors.Is 识别的
	// session.ErrSessionBusy，什么都不删。打开着这个对话的 Client 随后重新同步失败，交付 ConversationSyncFailed。
	DeleteConversation(ctx context.Context, request *DeleteConversationRequest) error
	// GetConversation 调 conversation/read，读对话记录，不打开对话。
	GetConversation(ctx context.Context, conversationID defs.ConversationID) (defs.Conversation, error)
	// GetSessionByID 调 session/get，只凭 SessionID 读 Session 记录（含所属对话），不打开对话；找不到时返回可用 errors.Is 识别的
	// runtime.ErrSessionNotFound。
	GetSessionByID(ctx context.Context, sessionID defs.SessionID) (defs.Session, error)
	// ListSessions 调 session/list，分页列出对话内的 Session 记录。
	ListSessions(ctx context.Context, request *ListSessionsRequest) (ListSessionsResult, error)
	// ListItems 调 session/items/list，分页读取一个 Session 的日志。
	ListItems(ctx context.Context, request *ListItemsRequest) (ListItemsResult, error)
	// ListTurns 调 session/turns/list，按 TurnID 分页列出一个 Session 的 Turn。
	ListTurns(ctx context.Context, request *ListTurnsRequest) (ListTurnsResult, error)
	// GetTurns 调 session/turns/get，按 TurnIDs 的顺序返回一个 Session 里找到的 Turn 记录，跳过不存在的。
	GetTurns(ctx context.Context, request *GetTurnsRequest) ([]defs.Turn, error)
	// SetConversationTitle 保存对话标题，空串表示清空。
	SetConversationTitle(ctx context.Context, conversationID defs.ConversationID, title string) error
	// SetConversationExecutorSettings 调 conversation/setExecutorSettings，让对话换上完整的新设置，返回保存后的记录；
	// 有 Session 在执行 Turn 时返回可用 errors.Is 识别的 session.ErrSessionBusy。打开着这个对话的 Client 随后自动重新同步，
	// ConversationSynced 带上新记录。
	SetConversationExecutorSettings(ctx context.Context, conversationID defs.ConversationID, settings defs.ExecutorSettings) (defs.Conversation, error)
	// SubmitInput 以用户身份向对话根 Session 提交内容：为本次提交生成 InputID，请求发出后断线时在重连后用同一 InputID 重发，
	// 直到得到结果或 ctx 结束；服务端按 InputID 判重。DisableSubmitInputRetry 为 true 时直接返回断线错误。
	SubmitInput(ctx context.Context, request *SubmitInputRequest) (defs.ItemID, error)
	// InterruptTurn 中断根 Session 的 Turn，返回 Turn ID。
	InterruptTurn(ctx context.Context, conversationID defs.ConversationID) (defs.TurnID, error)
	// SteerInput 将已排队用户输入移入指定轮，断线不重发。
	SteerInput(ctx context.Context, conversationID defs.ConversationID, itemID defs.ItemID, turnID defs.TurnID) error
	// InterruptTurnWithInput 置顶已排队用户输入并取消指定轮，断线不重发。
	InterruptTurnWithInput(ctx context.Context, conversationID defs.ConversationID, turnID defs.TurnID, itemID defs.ItemID) error
	// WithdrawInput 原子取走用户输入；returnContent 为 true 时返回完整用户消息内容，断线不重发。
	WithdrawInput(ctx context.Context, conversationID defs.ConversationID, itemID defs.ItemID, returnContent bool) ([]*defs.Content, error)
	// CompactContext 调 conversation/compact，让根 Session 开一个只压缩的 Turn，返回它的 TurnID；
	// 根 Session 忙时返回可用 errors.Is 识别的 session.ErrSessionBusy。
	CompactContext(ctx context.Context, conversationID defs.ConversationID) (defs.TurnID, error)
	// OpenConversation 打开一个对话，首次同步完成后返回：之前交付 ConversationSynced 与 SessionSynced（跟随的 Session 的全部历史与
	// 生成中 Item 列表；SkipHistory 时不含历史），之后交付它的实时事件，重连后自动补齐，每次同步都带上请求的环境变量
	// （服务端重启后按记录里的 Executor 设置冷打开）。跟随的 Session 由请求的 SessionID 指定，为空时是根 Session，
	// 对话换配置后的重新同步仍跟随同一个 Session。
	// 重新同步时服务端拒绝打开对话，交付 ConversationSyncFailed 并放弃这个对话。
	// 同一时刻只打开一个对话，打开新对话后旧对话的事件不再交付。
	OpenConversation(ctx context.Context, request *OpenConversationRequest) (defs.Conversation, error)
}

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

type ClientMCPConnectRequested struct {
	StreamID string
	ServerID string
}

type ClientMCPDisconnectRequested struct {
	StreamID string
}

type ClientMCPMessageReceived struct {
	StreamID string
	Message  json.RawMessage
}

type ClientOpt struct {
	// URL 是 OpenVaala 协议的 WebSocket 地址，例如 ws://127.0.0.1:8790/api/v1/openvaala。
	URL string
	// Token 非空时以 Authorization: Bearer 携带；URL 自带 ?token= 时可为空。
	Token string
	// Telemetry 是遥测管道，用于重连与通知丢弃的日志；nil 时使用全局兜底。
	Telemetry *telemetry.Telemetry
	// FailRequestsWhenDisconnected 为 true 时业务请求不等待连接；零值沿用等待重连。
	FailRequestsWhenDisconnected bool
	// DisableSubmitInputRetry 为 true 时提交后断线直接返回，不重发同一 InputID。
	DisableSubmitInputRetry bool
	// RPCFrameCapacity 是调试记录的帧数上限；0 关闭采集。
	RPCFrameCapacity int
}

type ConnectionChanged struct {
	State ConnectionState
	// Err 是导致重连的原因，手动重连或其他阶段为空。
	Err error
	// Attempt 是连续失败后的第几次重连，从 1 开始。
	Attempt int
	// RetryIn 是距离这次重连的等待时长。
	RetryIn time.Duration
	// ServerID 在 State 为 connected 时是 initialize 返回的 server_id，其他状态为空。
	ServerID string
}

type ConnectionState string

type ConversationSyncFailed struct {
	ConversationID defs.ConversationID
	// Err 是 serve 返回的错误。
	Err error
}

type ConversationSynced struct {
	ConversationID defs.ConversationID
	// Conversation 是 conversation/open 返回的对话记录，带当前的 Executor 设置；标题取对话订阅登记时的值。
	Conversation defs.Conversation
	// SessionInfos 是对话内全部 Session 的运行信息（订阅响应）。
	SessionInfos []runtime.SessionRuntimeInfo
}

type ConversationTitleChanged struct {
	ConversationID defs.ConversationID
	// Title 为空表示清空标题。
	Title string
}

type CreateConversationRequest struct {
	AgentName string
	// Model 为零值时使用 Agent 的默认模型。
	Model defs.ModelSelection
	// ExecutorSettings 里没有 local 目录时由服务端使用默认目录（配了 server.workspace_directory 时是它，否则是 serve 的启动目录）。
	ExecutorSettings defs.ExecutorSettings
	// Environment 为 nil 时本机命令继承 serve 进程的环境。
	Environment []string
	// Ephemeral 是否建临时对话？临时对话不存盘、不进对话列表，没有 Executor 和 Skill，ExecutorSettings 原样存进记录、不装配，
	// Environment 不使用；没有订阅者、也没有在跑的 Turn 一段时间后由服务端丢弃。
	Ephemeral bool
}

type DeleteConversationRequest struct {
	ConversationID defs.ConversationID
}

type ForkConversationRequest struct {
	ConversationID defs.ConversationID
	// BeforeTurnID 复制到这一轮之前（不含），回退重来用。
	BeforeTurnID defs.TurnID
	// LastTurnID 复制到这一轮（含）。
	LastTurnID defs.TurnID
	// Model 为零值时照抄来源根 Session 的模型。
	Model defs.ModelSelection
	// ExecutorSettings 是新对话的完整设置，一般传来源对话的；含义同 CreateConversationRequest。
	ExecutorSettings defs.ExecutorSettings
	// Environment 的含义同 CreateConversationRequest。
	Environment []string
}

type GetSkillsRequest struct {
	ConversationID   defs.ConversationID
	AgentName        string
	ExecutorSettings defs.ExecutorSettings
}

type GetTurnsRequest struct {
	ConversationID defs.ConversationID
	SessionID      defs.SessionID
	TurnIDs        []defs.TurnID
}

type GetWorkspaceDirectoriesRequest struct {
	ExecutorID    string
	Directory     string
	BaseDirectory string
}

type HookRunChanged struct {
	SessionID      defs.SessionID
	ConversationID defs.ConversationID
	// TurnID 是触发这次运行的 Turn。
	TurnID defs.TurnID
	// Run 是这次运行当时的完整记录：同一次运行（相同的 ID）开始时状态为 running，结束时为最终状态。
	Run *defs.HookRun
}

type ItemChanged struct {
	SessionID      defs.SessionID
	ConversationID defs.ConversationID
	// Type 区分开始、增量、完成和中断四种情况。
	Type      agent.AgentEventType
	TurnID    defs.TurnID
	ItemIndex int
	// Item 是开始、完成和中断时的完整 Item；中断且不用保存时为 nil，增量时为 nil。
	Item *defs.Item
	// Delta 只在增量时有值。
	Delta *agent.AgentItemDelta
}

type ItemsSaved struct {
	SessionID      defs.SessionID
	ConversationID defs.ConversationID
	TurnID         defs.TurnID
	Items          []runtimeprotocol.LoggedItem
}

type ListConversationsRequest struct {
	// Directories 按 local 目录筛选，为空时不限。
	Directories []string
	// SearchTerm 按区分大小写的标题子串筛选，为空时不限。
	SearchTerm string
	// Order 为零值时按 key（即创建顺序）升序。
	Order storage.Order
	// Cursor 为零值时从起点开始。
	Cursor dao.RecordCursor[defs.ConversationID]
	Limit  int
	// Archived 是否只列归档的对话？为 false 时只列没归档的。
	Archived bool
}

type ListConversationsResult struct {
	Conversations []dao.ConversationListEntry
	// NextCursor 为零值表示没有下一页。
	NextCursor dao.RecordCursor[defs.ConversationID]
}

type ListItemsRequest struct {
	ConversationID defs.ConversationID
	SessionID      defs.SessionID
	// Order 为零值时按流水号升序。
	Order storage.Direction
	// Cursor 为零值时从起点开始，翻页时取上一页的 NextCursor。
	Cursor storage.Ordinal
	// Limit 为零时由服务端决定每页条数。
	Limit int
}

type ListItemsResult struct {
	Items []runtimeprotocol.LoggedItem
	// NextCursor 为零表示没有下一页。
	NextCursor storage.Ordinal
}

type ListSessionsRequest struct {
	ConversationID defs.ConversationID
	Order          storage.Order
	Cursor         dao.RecordCursor[defs.SessionID]
	Limit          int
}

type ListSessionsResult struct {
	Sessions   []defs.Session
	NextCursor dao.RecordCursor[defs.SessionID]
}

type ListTurnsRequest struct {
	ConversationID defs.ConversationID
	SessionID      defs.SessionID
	Order          storage.Order
	Cursor         dao.RecordCursor[defs.TurnID]
	Limit          int
}

type ListTurnsResult struct {
	Turns      []defs.Turn
	NextCursor dao.RecordCursor[defs.TurnID]
}

type OpenConversationRequest struct {
	ConversationID defs.ConversationID
	// SessionID 是要跟随的 Session；为空时跟随根 Session。内容事件、补齐和 SessionSynced 都只针对它。
	SessionID defs.SessionID
	// Environment 为 nil 时本机命令继承 serve 进程的环境；对话已在服务端运行时沿用它第一次打开时的。
	Environment []string
	// SkipHistory 首次同步是否跳过已保存的历史？跳过时 SessionSynced.Items 为空，只交付订阅位置之后的内容；
	// 之后的重新同步照常从上次交付的位置补齐。
	SkipHistory bool
}

type RPCDirection string

type RPCFrame struct {
	ConnectionID uint64
	Sequence     uint64
	Time         time.Time
	Direction    RPCDirection
	Payload      json.RawMessage
}

type RPCLogChanged struct {
	DroppedFrames uint64
	Paused        bool
}

type ResolveWorkspaceDirectoryRequest struct {
	// ExecutorID 是在哪个 Executor 上解析。
	ExecutorID string
	// Directory 是用户写的目录：~、相对或绝对路径。
	Directory string
	// BaseDirectory 是当前目录；为空时相对路径拼在这个 Executor 的默认根目录后面。
	BaseDirectory string
}

type ResponseError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
}

type RunningConversationsChanged struct {
	ConversationIDs []defs.ConversationID
	IsKnown         bool
	Err             error
}

type SessionPendingInputsChanged struct {
	SessionID      defs.SessionID
	ConversationID defs.ConversationID
	PendingInputs  session.SessionPendingInputs
}

type SessionStatusChanged struct {
	ConversationID defs.ConversationID
	// Info 是完整的运行信息。
	Info runtime.SessionRuntimeInfo
}

type SessionSynced struct {
	SessionID      defs.SessionID
	ConversationID defs.ConversationID
	// Items 是上次交付位置之后补齐的已保存 Item；打开对话时为全部历史，SkipHistory 时为空。
	Items []runtimeprotocol.LoggedItem
	// StreamingItems 是跟随的 Session 正在生成的 Item 列表。
	StreamingItems []runtimeprotocol.StreamingItem
	// PendingInputs 是本次订阅读到的完整待处理用户列表。
	PendingInputs session.SessionPendingInputs
	// LastSavedOrdinal 是本次同步交付到的位置。
	LastSavedOrdinal storage.Ordinal
}

type SetConversationArchivedRequest struct {
	ConversationID defs.ConversationID
	Archived       bool
}

type SetSessionModelRequest struct {
	ConversationID defs.ConversationID
	SessionID      defs.SessionID
	Model          defs.ModelSelection
}

type SubmitInputRequest struct {
	ConversationID defs.ConversationID
	// Mode 省略时为 normal。
	Mode session.SessionInputMode
	// Content 原样交给服务端。
	Content []*defs.Content
}

type TerminalExited struct {
	TerminalID string
	ExitCode   int
	Error      string
}

type TerminalOpenRequest struct {
	// ExecutorID 为空时用 local Executor。
	ExecutorID string
	// Directory 为空时用该 Executor 的默认工作目录。
	Directory string
	// Rows、Cols 是初始行列数，为零时按 24×80。
	Rows, Cols uint16
	// Environment 为 nil 时 local Executor 的 shell 继承 serve 进程的环境。
	Environment []string
}

type TerminalOutput struct {
	TerminalID string
	Data       []byte
}

type ToolProgress struct {
	SessionID      defs.SessionID
	ConversationID defs.ConversationID
	TurnID         defs.TurnID
	// ItemIndex 指向本轮输出中的 ToolCall。
	ItemIndex int
	// Progress.CallID 是这个 ToolCall 的 CallID（中途接入时 ToolCall 可能已经保存、不在生成中 Item 列表里，按它找到调用），
	// Progress.Content 是本次输出的 JSON。
	Progress agent.AgentToolProgress
}

type TurnFinished struct {
	SessionID      defs.SessionID
	ConversationID defs.ConversationID
	TurnID         defs.TurnID
	// Status 在终态没有保存时为空。
	Status defs.TurnStatus
	// InputItemIDs 是本轮处理的输入 Item，可与 SubmitInput 返回的 ItemID 对应。
	InputItemIDs []defs.ItemID
	Error        string
}

type TurnStarted struct {
	SessionID      defs.SessionID
	ConversationID defs.ConversationID
	TurnID         defs.TurnID
}