runtime

type AgentInfo struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	// DefaultModel 是 Agent 的默认模型；Agent 没有指定默认模型时为零值。
	DefaultModel defs.ModelRef `json:"default_model,omitzero"`
}

type CompactContextRequest struct {
	ConversationID defs.ConversationID
}

type ContextUsage struct {
	// Window 是模型上下文窗口；0 表示窗口未知。
	Window int `json:"window"`
	// Tokens 是预计的输入 token 数。
	Tokens int `json:"tokens"`
	// Source 是 Tokens 的来源：实际基准加估算、整份估算，或还没有测量。
	Source ContextUsageSource `json:"source"`
}

type ContextUsageSource string

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

type ConversationSubscription struct {
	// Title 是订阅时已保存的标题。
	Title string
	// Sessions 是订阅时全部 Session 的运行信息，按 SessionID 排序。
	Sessions []SessionRuntimeInfo
	// Events 按顺序推送之后的运行信息变化和已保存标题的变化。
	Events <-chan ConversationEvent
	// contains filtered or unexported fields
}

type ConversationTitleChanged struct{ Title string }

type CreateConversationRequest struct {
	// AgentName 是根 Session 使用的 Agent 名。
	AgentName string
	// Model 是根 Session 的模型选择；零值时使用根 Agent 的默认模型。
	Model defs.ModelSelection
	// ExecutorSettings 补上缺的 local 目录后存进记录；新加入的未知 Executor 返回 conversation.ErrInvalidExecutorSettings。
	ExecutorSettings defs.ExecutorSettings
	// Environment 是客户端的环境变量（格式同 os.Environ），只给 local 种类的 Executor 执行命令用；nil 时继承 serve 进程的环境。
	Environment []string
	// Ephemeral 为 true 时建临时对话：存储在一个只属于它的 sqlite 内存库里，永远不进对话列表；
	// 没有订阅者、也没有 Session 在跑，满 UnsavedConversationIdleTimeout 后结束并丢弃，之后按 ID 读回「对话不存在」。
	// 临时对话没有 Executor 和 Skill，ExecutorSettings 原样存进记录。
	Ephemeral bool
}

type Definitions struct {
	Agents []*agent.AgentDefinition
	Models []*defs.ModelDefinition
	// MCPServers 是全部 MCP server 定义，含插件带来的。
	MCPServers []*mcpclient.ServerDefinition
	// Hooks 是全部 hook 定义（含插件带来的），已按配置顺序排列；为空时对话也有一个不含任何 hook 的 hook.Hooks。
	Hooks []*hook.HookDefinition
	// Executors 是全部 Executor：local、builtin，再加 executors/ 里配置的，按这个顺序。
	Executors []*defs.ExecutorDefinition
	// Skills 是所有对话共用的 skill：skills.directory、builtin、各插件，按这个顺序去重。
	Skills []*skill.Skill
}

type DeleteConversationRequest struct {
	ConversationID defs.ConversationID
}

type ForkConversationRequest struct {
	ConversationID defs.ConversationID
	// BeforeTurnID 复制到这一轮之前（不含），回退重来用；LastTurnID 复制到这一轮（含）。
	// 两个最多填一个；都不填时复制所有已结束的轮次。
	BeforeTurnID defs.TurnID
	LastTurnID   defs.TurnID
	// Model 是新根 Session 的模型；零值时照抄来源根 Session 的模型。
	Model defs.ModelSelection
	// ExecutorSettings、Environment 和 CreateConversationRequest 一样；调用方一般传来源对话的设置。来源记录里就有、
	// 配置中已不存在的 Executor 只记 Warn。
	ExecutorSettings defs.ExecutorSettings
	Environment      []string
}

type GetConversationRequest struct {
	ConversationID defs.ConversationID
}

type GetSessionByIDRequest struct {
	SessionID defs.SessionID
}

type GetSessionContextUsageRequest struct {
	ConversationID defs.ConversationID
	SessionID      defs.SessionID
}

type GetSessionDetailsRequest struct {
	ConversationID defs.ConversationID
	SessionID      defs.SessionID
}

type GetSkillsRequest struct {
	ConversationID defs.ConversationID
	AgentName      string
	// ExecutorSettings 只在没有 ConversationID 时用：草稿对话按它找默认 Executor 扫项目目录和主目录。
	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 InterruptTurnRequest struct {
	ConversationID defs.ConversationID
}

type InterruptTurnWithInputRequest struct {
	ConversationID defs.ConversationID
	ItemID         defs.ItemID
	TurnID         defs.TurnID
}

type LastRequestUsage struct {
	ModelCallID defs.ModelCallID `json:"model_call_id"`
	// Model 是这次普通调用使用的模型。
	Model defs.ModelRef `json:"model"`
	// Usage 是服务商上报的用量。
	Usage defs.TokenUsage `json:"usage"`
	// EstimatedTokens 是调用前未经实际用量校正的本地估算。
	EstimatedTokens int `json:"estimated_tokens"`
}

type ListItemsRequest struct {
	ConversationID defs.ConversationID
	SessionID      defs.SessionID
	Order          storage.Direction
	Cursor         storage.Ordinal
	Limit          int
}

type ListModelsRequest struct {
	AgentName string
}

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

type ModelList struct {
	Models []*defs.ModelDefinition `json:"models"`
	// AgentDefaultModel 是请求中 Agent 的默认模型；没有指定 Agent 时为零值。
	AgentDefaultModel defs.ModelRef `json:"agent_default_model,omitzero"`
}

type OpenConversationRequest struct {
	ConversationID defs.ConversationID
	// Environment 和 CreateConversationRequest.Environment 相同。
	Environment []string
}

type OpenTerminalWorkspaceRequest struct {
	// ExecutorID 为空时用 local Executor。
	ExecutorID string
	// Directory 为空时用该 Executor 的默认工作目录；否则按 ResolveWorkspaceDirectory 的规则解析并检查它是目录。
	Directory string
	// Environment 的含义同 CreateConversationRequest；只给 local 种类的 Executor 用。
	Environment []string
}

type ResolveWorkspaceDirectoryRequest struct {
	// ExecutorID 是要在哪个 Executor 上解析目录。
	ExecutorID string
	// Directory 是用户写的目录。
	Directory string
	// BaseDirectory 是当前目录；为空时用这个 Executor 的默认根目录。
	BaseDirectory string
}

type RunningConversations struct {
	ConversationIDs []defs.ConversationID `json:"conversation_ids"`
}

type RunningConversationsSubscription struct {
	Initial RunningConversations
	Events  <-chan RunningConversations
	// contains filtered or unexported fields
}

type Runtime interface {
	// Run 运行到上下文结束，停止并等待全部对话后返回；只能调用一次。需要运行实例的方法在 Run 启动前等待，Run 返回后返回 ErrRuntimeStopped。
	Run(ctx context.Context) error
	// IsIdle 全部已打开对话是否都没有运行中的 Turn 或后台命令？包括子 Agent；Runtime 已停止时返回 ErrRuntimeStopped。
	IsIdle(ctx context.Context) (bool, error)

	// CreateConversation 按 Agent、模型、Executor 设置和环境创建并启动对话；模型目录为空返回 ErrNoModelConfigured，设置无效返回 conversation.ErrInvalidExecutorSettings。
	CreateConversation(ctx context.Context, request *CreateConversationRequest) (defs.Conversation, error)
	// OpenConversation 对话已打开时返回最新记录，否则按记录里的设置装配并启动；同一对话同时打开只装配一次，记录不存在返回 ErrConversationNotFound。
	OpenConversation(ctx context.Context, request *OpenConversationRequest) (defs.Conversation, error)
	// IsConversationOpen 对话是否有尚未退出的运行实例？
	IsConversationOpen(ctx context.Context, request *GetConversationRequest) (bool, error)
	// SetConversationExecutorSettings 更新完整 Executor 设置并返回记录；有 Session 在执行 Turn 时返回 session.ErrSessionBusy，新增未知 Executor 返回 conversation.ErrInvalidExecutorSettings。
	SetConversationExecutorSettings(ctx context.Context, request *SetConversationExecutorSettingsRequest) (defs.Conversation, error)
	// GetConversation 读取对话记录，对话没打开也能读；找不到时返回 ErrConversationNotFound。
	GetConversation(ctx context.Context, request *GetConversationRequest) (defs.Conversation, error)
	// ListConversations 分页读取匹配的对话及根 Session；Archived 为 true 只查已归档，否则只查未归档。
	ListConversations(ctx context.Context, request *dao.ListConversationsRequest) (storage.Page[dao.ConversationListEntry, dao.RecordCursor[defs.ConversationID]], error)
	// SetConversationTitle 保存标题的前 256 个字符，已打开对话的订阅者会收到标题变化。
	SetConversationTitle(ctx context.Context, request *SetConversationTitleRequest) error
	// ForkConversation 复制已保存对话到指定轮次并打开分叉；没有可复制轮次时新建未保存对话，临时和未保存来源返回 ErrConversationNotFound。
	ForkConversation(ctx context.Context, request *ForkConversationRequest) (defs.Conversation, error)
	// SetConversationArchived 更新归档时间并返回记录，状态相同时不写入；临时和未保存对话返回 ErrConversationNotFound。
	SetConversationArchived(ctx context.Context, request *SetConversationArchivedRequest) (defs.Conversation, error)
	// DeleteConversation 停止对话并删除全部记录和历史；有 Session 在执行 Turn 时返回 session.ErrSessionBusy，临时和未保存对话返回 ErrConversationNotFound。
	DeleteConversation(ctx context.Context, request *DeleteConversationRequest) error

	// SubmitInput 将输入交给已打开对话的根 Session，返回 ItemID；普通新对话先保存，用户输入接收后用正文给空标题命名。
	SubmitInput(ctx context.Context, request *SubmitInputRequest) (defs.ItemID, error)
	// InterruptTurn 请求取消根 Session 的活动 Turn，不等待结束；没有活动 Turn 时返回空 TurnID。
	InterruptTurn(ctx context.Context, request *InterruptTurnRequest) (defs.TurnID, error)
	// SteerInput 将根 Session 的排队用户输入移入指定轮。
	SteerInput(ctx context.Context, request *SteerInputRequest) error
	// InterruptTurnWithInput 将排队用户输入置顶并取消指定轮。
	InterruptTurnWithInput(ctx context.Context, request *InterruptTurnWithInputRequest) error
	// WithdrawInput 原子取走根 Session 的完整待处理用户输入组。
	WithdrawInput(ctx context.Context, request *WithdrawInputRequest) ([]*defs.Item, error)
	// CompactContext 请求根 Session 启动压缩 Turn 并返回 TurnID；有活动 Turn 或排队输入时返回 session.ErrSessionBusy，普通新对话先保存。
	CompactContext(ctx context.Context, request *CompactContextRequest) (defs.TurnID, error)
	// SubscribeConversation 订阅已打开对话的标题与全部 Session 运行信息，先返回初始信息再有序推送变化，订阅上下文结束后退订。
	SubscribeConversation(ctx context.Context, request *SubscribeConversationRequest) (*ConversationSubscription, error)
	// SubscribeSession 订阅已打开对话中一个 Session 的内容，订阅上下文结束后退订。
	SubscribeSession(ctx context.Context, request *SubscribeSessionRequest) (*SessionSubscription, error)
	// SubscribeRunningConversations 返回当前运行集合并订阅变化，ctx 结束后退订。
	SubscribeRunningConversations(ctx context.Context) (subscription *RunningConversationsSubscription, err error)

	// GetSessionContextUsage 读取已打开对话中一个 Session 的上下文占用详情，取自最近的测量和模型调用记录。
	GetSessionContextUsage(ctx context.Context, request *GetSessionContextUsageRequest) (SessionContextUsage, error)
	// GetSessionDetails 读取已打开对话中的 Session 配置和最新标题。
	GetSessionDetails(ctx context.Context, request *GetSessionDetailsRequest) (conversation.SessionDetails, error)
	// GetMCPServers 返回已打开对话的执行环境及客户端 MCP 连接情况，不等待连接；未打开时返回 ErrConversationNotOpen。
	GetMCPServers(ctx context.Context, request *GetConversationRequest) ([]conversation.MCPServerInfo, error)
	// SetClientMCPServers 替换客户端为已打开对话登记的全部 MCP server，下个 Turn 起生效；空列表移除全部，无效登记返回错误且保留原登记。
	SetClientMCPServers(ctx context.Context, request *SetClientMCPServersRequest) error
	// ListModels 返回公开模型目录和指定 Agent 的默认模型，不含连接信息与凭证。
	ListModels(ctx context.Context, request *ListModelsRequest) (ModelList, error)
	// GetHooks 按配置顺序返回 Hook 信息，未配置时返回空切片。
	GetHooks(ctx context.Context) ([]*hook.HookInfo, error)
	// ListAgents 按配置顺序返回当前定义中的 Agent 名、说明和默认模型，不含系统指令。
	ListAgents(ctx context.Context) ([]AgentInfo, error)
	// ListExecutors 按 local、builtin、配置顺序返回 Executor 说明和默认目录。
	ListExecutors(ctx context.Context) ([]conversation.ExecutorDetails, error)
	// ResolveWorkspaceDirectory 按当前 Executor 定义解析工作目录；SSH Executor 每次调用建立连接，结束后断开。
	ResolveWorkspaceDirectory(ctx context.Context, request *ResolveWorkspaceDirectoryRequest) (string, error)
	// OpenTerminalWorkspace 按当前 Executor 定义为一个终端新建独立工作区，不借用任何对话的工作区；virtual Executor 返回 workspace.ErrTTYUnsupported。
	OpenTerminalWorkspace(ctx context.Context, request *OpenTerminalWorkspaceRequest) (*TerminalWorkspace, error)
	// GetWorkspaceDirectories 列出指定 Executor 上一个目录的普通直接子目录，请求结束后关闭临时工作区。
	GetWorkspaceDirectories(ctx context.Context, request *GetWorkspaceDirectoriesRequest) (directories *conversation.WorkspaceDirectories, err error)
	// SetDefinitions 替换整份定义，并行更新空闲对话；等待全部更新结束，结果列出未更新的忙碌对话，单个更新失败只记日志并保留原配置。
	SetDefinitions(ctx context.Context, request *Definitions) (SetDefinitionsResult, error)
	// GetSkills 返回对话根 Agent 或草稿 Agent 的可用 Skill 目录；草稿按 Executor 设置扫描项目目录和主目录。
	GetSkills(ctx context.Context, request *GetSkillsRequest) ([]skill.SkillInfo, error)
	// SetSessionModel 保存已打开对话中 Session 的模型和推理强度，下个 Turn 起生效，返回记录并推送运行信息；已保存但通知 Session 失败时，仍推送运行信息并返回记录和错误。
	SetSessionModel(ctx context.Context, request *SetSessionModelRequest) (defs.Session, error)

	// ListSessions 分页读取对话内的 Session 记录。
	ListSessions(ctx context.Context, request *dao.ListSessionsRequest) (storage.Page[defs.Session, dao.RecordCursor[defs.SessionID]], error)
	// GetSessionByID 从共享库按 SessionID 读取记录（含所属 ConversationID）；未找到时返回 ErrSessionNotFound。
	GetSessionByID(ctx context.Context, request *GetSessionByIDRequest) (defs.Session, error)
	// ListTurns 按请求排序分页读取 Session 的 Turn，默认按 TurnID，也支持 UpdatedAt；不要求对话已打开。
	ListTurns(ctx context.Context, request *ListTurnsRequest) (storage.Page[defs.Turn, dao.RecordCursor[defs.TurnID]], error)
	// GetTurns 按请求顺序返回找到的 Turn，跳过不存在的记录，不要求对话已打开。
	GetTurns(ctx context.Context, request *GetTurnsRequest) ([]defs.Turn, error)
	// ListItems 分页读取对话内一个 Session 的日志。
	ListItems(ctx context.Context, request *ListItemsRequest) (storage.Page[dao.LoggedItem, storage.Ordinal], error)
}

type RuntimeOpt struct {
	// Records、Logs 是共用库的记录和日志存储；Runtime 用它们建共用的 DAO，也用作新对话暂存记录的目标。
	Records storage.RecordStorage
	Logs    storage.LogStorage
	// Definitions 是初始的整份定义：Agent 至少一个，每个 Session 按持久化的 AgentName 选择；各 Agent 的默认模型和摘要模型
	// 引用模型目录里的项，模型目录为空时不能新建对话，等 SetDefinitions 加上模型；MCP server 只给至少一个 Agent 会用到的建连接。
	Definitions *Definitions
	// Telemetry 是遥测管道，由 Run 挂到 ctx 供全部对话使用；nil 时使用全局兜底。
	Telemetry *telemetry.Telemetry
	// UnsavedConversationIdleTimeout 是没保存的对话（临时对话、还没收到第一条输入的新对话）没有订阅者、也没有 Session 在跑后，
	// 等多久结束并丢弃；NewRuntimeOpt 默认 60 秒。
	UnsavedConversationIdleTimeout time.Duration
	// MaxImageBytes 是 read_file 交给模型的单张图片上限，来自 tools.max_image_kb；serve 启动时定，reload 不变。
	// NewRuntimeOpt 默认 500 KiB。
	MaxImageBytes int
}

type SessionContextUsage struct {
	// Window 是下一次请求所用模型的上下文窗口；0 表示窗口未知。
	Window int `json:"window"`
	// ThresholdTokens 是自动压缩阈值，按下一模型的窗口和最大输出计算；还没有测量时为 0。
	ThresholdTokens int `json:"threshold_tokens"`
	// NextRequest 与同一时刻的 SessionRuntimeInfo.Context 相同。
	NextRequest ContextUsage `json:"next_request"`
	// LastRequest 在还没有上报过用量的普通调用时为 nil。
	LastRequest *LastRequestUsage `json:"last_request,omitempty"`
	// SystemTokens、ToolTokens 是最近一次测量中系统提示词和工具定义的占用；还没有测量时为 0。
	SystemTokens int `json:"system_tokens"`
	ToolTokens   int `json:"tool_tokens"`
	// Items 是本轮最近一次统一测量的 Item 分类估算；还没有测量时为空。
	Items []agent_context.ItemTokens `json:"items"`
}

type SessionRuntimeInfo struct {
	Session        defs.Session         `json:"session"`
	State          session.SessionState `json:"state"`
	ActiveTurnID   defs.TurnID          `json:"active_turn_id,omitempty"`
	LastTurnID     defs.TurnID          `json:"last_turn_id,omitempty"`
	LastTurnStatus defs.TurnStatus      `json:"last_turn_status,omitempty"`
	// ActiveTurnModel 是活动 Turn 使用的模型和推理强度；没有活动 Turn 时为零值。所选模型见 Session.Model。
	ActiveTurnModel defs.ModelSelection `json:"active_turn_model,omitzero"`
	// Context 是下一次请求的预计占用。
	Context ContextUsage `json:"context"`
	// Usage 是累计用量：对话加载时已保存 Turn 的用量之和，加上之后各次模型调用上报的用量。
	Usage defs.TokenUsage `json:"usage"`
}

type SessionSubscription struct {
	// LastSavedOrdinal 是订阅时已转发的最后一条已保存日志的流水号；它及之前的日志用 ListItems 补齐。
	LastSavedOrdinal storage.Ordinal
	// StreamingItems 是订阅时该 Session 活动 Turn 中已开始、尚未保存的 Item，按首次出现顺序，带 ItemIndex：
	// 活动 Turn 中可能同时有多个 Item 在生成（例如推理与消息），后续增量事件只用 ItemIndex 定位所属 Item。
	StreamingItems []StreamingItem
	// PendingInputs 是订阅时待处理用户输入及可接收补充的轮。
	PendingInputs session.SessionPendingInputs
	// Events 紧接着订阅时的初始信息开始推送；事件对象由全部订阅者共享，只读。
	Events <-chan conversation.ConversationEvent
	// contains filtered or unexported fields
}

type SetClientMCPServersRequest struct {
	ConversationID defs.ConversationID
	// ClientID 是 serve 上这条客户端连接的 ID。
	ClientID string
	Servers  []conversation.ClientMCPServer
}

type SetConversationArchivedRequest struct {
	ConversationID defs.ConversationID
	Archived       bool
}

type SetConversationExecutorSettingsRequest struct {
	ConversationID   defs.ConversationID
	ExecutorSettings defs.ExecutorSettings
}

type SetConversationTitleRequest struct {
	ConversationID defs.ConversationID
	Title          string
}

type SetDefinitionsResult struct {
	// BusyConversationIDs 是正在执行 Turn 或有后台命令没结束、这次没有换上新定义的对话；它们空闲后再 reload 才用上新定义。
	BusyConversationIDs []defs.ConversationID `json:"busy_conversation_ids"`
}

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

type SteerInputRequest struct {
	ConversationID defs.ConversationID
	ItemID         defs.ItemID
	TurnID         defs.TurnID
}

type StreamingItem struct {
	ItemIndex int
	Item      *defs.Item
}

type SubmitInputRequest struct {
	ConversationID defs.ConversationID
	// InputID 可选：根 Session 本次运行期内重复的 InputID 只接收一次，返回首次的 ItemID。
	InputID defs.InputID
	Mode    session.SessionInputMode
	// From 必须是用户或 Agent 身份。
	From    *defs.Address
	Content []*defs.Content
}

type SubscribeConversationRequest struct {
	ConversationID defs.ConversationID
}

type SubscribeSessionRequest struct {
	ConversationID defs.ConversationID
	SessionID      defs.SessionID
}

type TerminalWorkspace struct {
	Workspace workspace.Workspace
	// ExecutorID 是实际使用的 Executor。
	ExecutorID string
	// Directory 是解析后的绝对起始目录。
	Directory string
}

type WithdrawInputRequest struct {
	ConversationID defs.ConversationID
	ItemID         defs.ItemID
}