session

type PendingInput struct {
	ItemID     defs.ItemID `json:"item_id"`
	Preview    string      `json:"preview"`
	ImageCount int         `json:"image_count"`
	IsSteer    bool        `json:"is_steer"`
}

type Session interface {
	// GetID 返回 Session ID。
	GetID() defs.SessionID
	// Run 修复最近的 Turn 后串行处理收件箱；停止时取消活动 Turn、丢弃排队输入，等 Turn 和后台命令结束后返回。
	// events 不能为 nil，调用方要一直读到它关闭；events 关闭时，其他方法已经按 Session 已停止处理。
	Run(ctx context.Context, events chan<- SessionEvent) error
	// HandleInput 接收输入并返回 ItemID，同一 InputID 在本次运行内只接收一次；哪个 Turn 处理了它，看 SessionTurnFinished.InputItemIDs。
	// 输入无效、Session 已开始停止、所选模型不在目录里、选中的 Skill 读不出来或 idle_only 遇到活动 Turn 时返回错误，这条输入不排队；
	// 重新选择模型后可以再提交。
	HandleInput(ctx context.Context, input *SessionInput) (defs.ItemID, error)
	// GetStatus 返回执行状态和最近 Turn，停止后返回最终状态；查询可能短暂落后于已发出的 Turn 结束事件。
	GetStatus(ctx context.Context) (SessionStatus, error)
	// IsTerminalBusy 本 Session 是否还有未结束或正在启动的后台命令？只查命令记录，与是否在执行 Turn 无关。
	IsTerminalBusy() bool
	// InterruptTurn 请求取消活动 Turn 并返回它的 ID，不等取消完成；没有活动 Turn 时返回空。
	// 根 Session 被中断后，Agent 消息继续排队但不启动 Turn，收到下一条用户输入后恢复。
	InterruptTurn(ctx context.Context) (defs.TurnID, error)
	// SteerInput 将普通排队用户输入完整移入指定轮的未读补充。
	SteerInput(ctx context.Context, itemID defs.ItemID, turnID defs.TurnID) (err error)
	// InterruptTurnWithInput 将选中用户输入与旧轮未读补充同批置顶，并取消指定轮。
	InterruptTurnWithInput(ctx context.Context, turnID defs.TurnID, itemID defs.ItemID) (err error)
	// WithdrawInput 原子取走待处理的完整用户输入组。
	WithdrawInput(ctx context.Context, itemID defs.ItemID) (items []*defs.Item, err error)
	// WaitSteer 等活动 Turn 的未读补充输入，返回副本，不取走；已有输入时立即返回，没有活动 Turn、Turn 结束或 Session 已停止时返回空、不报错。
	// 调用方先取消时返回 ctx.Err()。
	WaitSteer(ctx context.Context) ([]*defs.Item, error)
	// CompactContext 空闲时启动只压缩的 Turn 并返回它的 ID，不等压缩完成；有活动 Turn 或排队的用户输入时返回 ErrSessionBusy，
	// 排队的 Agent 消息不算忙；已开始停止或所选模型不在目录里时返回错误。
	CompactContext(ctx context.Context) (defs.TurnID, error)
	// SelectModel 接收 Conversation 已校验并保存的模型选择，从下个 Turn 起使用，不影响正在执行的 Turn；Session 已停止时返回 nil。
	SelectModel(ctx context.Context, model defs.ModelSelection) error
}

type SessionAgentEvent struct {
	TurnID defs.TurnID
	Event  *agent.AgentEvent
}

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

type SessionHookRunEvent struct {
	TurnID defs.TurnID
	Run    *defs.HookRun
}

type SessionInput struct {
	Mode SessionInputMode
	// Item 是输入消息，ID 由调用方生成，还没分配 TurnID 和 ModelCallID。
	Item *defs.Item
	// InputID 可选：本次运行期内重复的 InputID 只接收一次，返回首次接收的 ItemID。
	InputID defs.InputID
}

type SessionInputMode string

type SessionItemsSaved struct {
	TurnID defs.TurnID
	Items  []dao.LoggedItem
}

type SessionOpt struct {
	// Session 是持久化的 Session 记录。
	Session  defs.Session
	Query    dao.Query
	Mutation dao.Mutation
	Client   llmkit.Client
	// Agent 是本 Session 每个 Turn 使用的 Agent 定义。
	Agent *agent.AgentDefinition
	// Models 是只读的模型目录，由 Conversation 建立索引后共享给全部 Session。
	Models map[defs.ModelRef]*defs.ModelDefinition
	// Environments 是本对话的执行环境实例，第一个为默认；由 Conversation 持有，Session 只借用。
	Environments []executor.ExecutionEnvironment
	// AgentTools 是 Conversation 为本 Session 建的协作工具，在 Agent 侧执行。
	AgentTools []executor.Tool
	// ClientMCPServers 提供 Conversation 持有的客户端 MCP 工具，nil 表示没有。
	ClientMCPServers executor.ClientMCPServers
	// Skills 是本 Agent 可用的 Skill，接收用户输入时按消息里的斜杠指令读取正文。
	Skills []*skill.Skill
	// Hooks 交给每个 Turn 触发 SessionStart、SubagentStart、UserPromptSubmit 与 Stop 等事件；nil 表示没有 hook。
	Hooks hook.Hooks
	// HookStartSource 是本次启动后第一个非压缩 Turn 触发 SessionStart 的来源：startup 或 resume；为空时不触发
	// （重开的子 Session）。子 Session 的 Turn 按它触发 SubagentStart。
	HookStartSource string
}

type SessionPendingInputs struct {
	SteerTurnID defs.TurnID    `json:"steer_turn_id,omitempty"`
	Inputs      []PendingInput `json:"inputs"`
}

type SessionPendingInputsUpdated struct {
	PendingInputs SessionPendingInputs
}

type SessionState string

type SessionStatus struct {
	State SessionState `json:"state"`
	// ActiveTurnID 是活动 Turn，没有时为空。
	ActiveTurnID defs.TurnID `json:"active_turn_id,omitempty"`
	// PendingInputCount 是排队等新 Turn 的输入条数，用户输入和 Agent 消息都算。
	PendingInputCount int `json:"pending_input_count"`
	// LastTurnID 是最近一个 Turn。
	LastTurnID defs.TurnID `json:"last_turn_id,omitempty"`
	// LastTurnStatus 是最近一个 Turn 保存的终态，终态没保存时为空。
	LastTurnStatus defs.TurnStatus `json:"last_turn_status,omitempty"`
}

type SessionTurnFinished struct {
	TurnID defs.TurnID
	// InputItemIDs 是本轮读入的全部输入，包括补充输入。
	InputItemIDs []defs.ItemID
	// Status 是本轮的终态，只在终态已保存时填写。
	Status defs.TurnStatus
	// Outputs 是本轮的输出 Item。
	Outputs []*defs.Item
	// FinalModelCallID 是最后一次模型调用的 ID，只在 completed 时填写。
	FinalModelCallID defs.ModelCallID
	// Err 是 Turn.Run 返回的错误。
	Err error
}

type SessionTurnStarted struct {
	TurnID defs.TurnID
	// Model 是本 Turn 使用的模型和推理强度。
	Model defs.ModelSelection
}