turn

type Turn interface {
	// Run 保存输入、加载历史、执行 Agent 并返回本轮结果；写库不受 ctx 取消影响。
	// 写输入前运行启动和用户输入 hook；输入被拦下或 hook 要求结束时跳过 Agent，记录 completed。
	// 被拦下的输入不保存，但仍计入 InputItemIDs；UserPromptSubmit 只处理用户输入。
	// 调用方持续读取 events 到 Run 返回，nil 表示不订阅；IsCompactOnly 时 input 传 nil。
	Run(ctx context.Context, input []*defs.Item, events chan<- TurnEvent) (TurnResult, error)
}

type TurnAgentEvent struct{ Event *agent.AgentEvent }

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

type TurnHookRunEvent struct{ Run *defs.HookRun }

type TurnInbox interface {
	// TakeSteer 取走挂在 turnID 上的补充输入；finish 为 true 且没取到输入时，停止向这个 Turn 投递。
	TakeSteer(ctx context.Context, turnID defs.TurnID, finish bool) ([][]*defs.Item, error)
}

type TurnItemsSaved struct{ Items []dao.LoggedItem }

type TurnOpt struct {
	TurnID defs.TurnID
	// ConversationID 是所属对话，读写 Item 和保存 Turn 记录时据此定位对话目录。
	ConversationID defs.ConversationID
	SessionID      defs.SessionID
	// Agent 提供名称、说明和系统指令。
	Agent    *agent.AgentDefinition
	Query    dao.Query
	Mutation dao.Mutation
	Client   llmkit.Client
	// ToolExecutor 是本 Session 的工具表，交给 Agent 列出工具和执行调用；nil 表示没有工具。
	ToolExecutor executor.ToolExecutor
	// Environments 是本对话的执行环境，第一个是默认环境；Turn 用它记录本轮 Executor、交给 Agent 读目录规则，并在默认环境运行 hook。
	Environments []executor.ExecutionEnvironment
	// Inbox 提供本轮的补充输入。
	Inbox TurnInbox
	// Model 是本 Turn 使用的模型，指向目录里的只读定义。
	Model *defs.ModelDefinition
	// ReasoningEffort 是已解析的推理强度；模型不支持选择时为空。
	ReasoningEffort string
	// CompactModel 是本 Turn 压缩使用的模型。
	CompactModel *defs.ModelDefinition
	// PreviousModel 是上一个 Turn 使用的模型；零值表示还没有。
	PreviousModel defs.ModelRef
	// PreviousContextUsage 是最近一次完整普通调用的报告；上一轮没有完整普通调用时沿用更早的报告，没有时为 nil。
	PreviousContextUsage *defs.TurnContextUsage
	// PreviousExecutors 是上一个 Turn 开始时的 Executor 列表；为空表示还没有上一轮。
	PreviousExecutors []defs.TurnExecutor
	// IsCompactOnly 这个 Turn 是否只压缩上下文？是的话 Run 的 input 为空，不写输入和模型、Executor 变化 Item，
	// 只让 Agent 把历史压成摘要；Turn 记录照常写 running 和终态。
	IsCompactOnly bool
	// Hooks 在写输入前触发 SessionStart、SubagentStart 和 UserPromptSubmit，也交给 Agent 触发工具与 Stop 事件；
	// nil 或 Environments 为空表示不触发 hook。
	Hooks hook.Hooks
	// Session 是本 Turn 所属 Session 的记录，随 hook 事件交给脚本；ParentSessionID 非空表示子 Session。
	Session defs.Session
	// HookStartSource 只有 Session 启动后的第一个非压缩 Turn 非空：startup 或 resume。
	// 非空时 Turn 在写输入前触发 SessionStart（子 Session 触发 SubagentStart，不带来源）；为空则不触发。
	HookStartSource string
}

type TurnResult struct {
	// InputItemIDs 按读入顺序保存首批输入和每组补充输入的首个 Item ID；被 UserPromptSubmit 拦下、没有保存的输入也算。
	InputItemIDs []defs.ItemID
	// Outputs 是 Agent 返回的全部草稿；Agent 没运行时为空。
	Outputs []*defs.Item
	// FinalModelCallID 是最后一次成功的普通模型调用，只在 completed 时填写。
	FinalModelCallID defs.ModelCallID
	// Status 是已保存的终态；终态没保存时为空。
	Status defs.TurnStatus
	// ContextUsage 是最近一次完整普通调用的报告；本轮没有完整普通调用时沿用上一轮的报告，模型切换后为 nil。
	ContextUsage *defs.TurnContextUsage
}