type RunStatus string     // queued | running | waiting_human | cancelling | completed | failed | cancelled
type Phase string        // init | user_input | llm_result | tools_batch_result | human_approved | human_abort | compression_result | error
type InstructionType string // load_context | call_llm | call_tools_batch | request_human_approve | compress_context | finish

// AgentState 是一次 Agent 执行的可序列化状态。
type AgentState struct {
	SessionID       string
	RunID           string
	TurnID          *string
	Status          RunStatus
	StepIndex       int               // 已提交拍号；下一拍必须是 StepIndex+1
	Config          RunConfigSnapshot // 启动后冻结，只读
	CancelRequested bool              // 用户已请求取消
	StopReason      *StopReason       // 终态原因
	ForceFinish     bool              // 超 max turns 后剥 tools 收尾
	Checkpoint      ToolCheckpoint    // 工具恢复点
	PendingApproval *string           // 未裁定审批 id
	StartedAt       *time.Time
	FinishedAt      *time.Time
}

// ToolCheckpoint 记录同一批 tool_call 的执行状态。
type ToolCheckpoint struct {
	TurnID    string
	Completed []string      // 已执行完毕的 tool_call_id
	Approved  []string      // 已批准 tool_call_id
	Denied    []string      // 已拒绝 tool_call_id
	Pending   []tool.Call   // 待执行 tool_call（可能多个）
	Results   []tool.Result // 已产生结果，按原始顺序
}

type StepJob struct {
	RunID     string
	StepIndex int               // 幂等去重键
	Phase     Phase             // 为什么被叫醒
	Payload   json.RawMessage
	Attempt   int               // 本拍重试次数
}

type CallToolsBatchPayload struct {
	Calls       []tool.Call   // 本次全部 tool_call
	Mode        string        // "serial" | "parallel"
	MaxParallel int           // 并行上限
}

type ToolsBatchResultPayload struct {
	Results []tool.Result // 含成功 / 失败 / 拒绝 / 跳过，按原始顺序
}

type Instruction struct {
	Type    InstructionType
	Payload json.RawMessage
}

type Fact struct {
	Type    EventType
	TurnID  *string
	Payload json.RawMessage
}

type StepResult struct {
	State AgentState
	Facts    []Fact
	Next     *StepJob // 只有 running 时才非空
}

type Brain interface {
	Decide(phase Phase, payload json.RawMessage, state AgentState) ([]Instruction, error)
}

// Engine 执行一拍。不写库、不发事件、不调度下一拍。
type Engine interface {
	Step(ctx context.Context, state AgentState, job StepJob) (StepResult, error)
}

// Coordinator 是 AgentState 的唯一写入点，也是两总线唯一扇出点。
type Coordinator interface {
	CreateAgentState(sessionID, triggerMessageID string, mode AgentMode, config RunConfigSnapshot) (runID string, err error) // 创建 queued 的 AgentState
	ClaimSession(sessionID, runID string) error                          // 标为 Session 的 active Run
	Enqueue(job StepJob) error                                           // 向执行总线投递作业
	TryClaimStep(runID string, stepIndex int) (ok bool, err error)       // 互斥领取一拍
	LoadAgentState(runID string) (AgentState, error)                         // 加载 AgentState
	AppendFact(runID string, fact Fact) (AgentEvent, error)              // 拍内写事实并发布事件
	CommitStep(runID string, result StepResult) error                    // 提交 AgentState 并扇出后续作业
	RequestCancel(runID string) error                                    // 请求取消 Run
	RecoverActive() error                                                // 启动时补投可继续作业
	DequeueNext(sessionID, finishedRunID string) error                 // 终态后领取下一个 queued Run
}

// Worker 消费执行总线。
type Worker interface {
	Start(ctx context.Context) error // 启动消费者
	Submit(job StepJob) error        // 投递作业；队列满则失败，不丢 AgentState
	Cancel(runID string)             // 取消 Run 的飞行拍
}

// 用户发起会话
Session.Create(...)

// 用户输入文本
Message.Insert(...)
Run.Start(...)
Session.ClaimActiveRun(...)
Event.Append(run.created)
Coordinator.Enqueue(StepJob{Phase: user_input})

// 执行：user_input 拍
TryClaimStep(...)
LoadAgentState(...)
Brain.Decide(user_input, state) → call_llm
Context.Load(...)
Context.CompactIfNeeded(...)
Context.Build(...)
Model.Stream(...)
  Event.Append(assistant.delta)
Message.Insert(...)
Memory.IndexMessage(...)
CommitStep(...) // 若还有 tool 则投下一拍

// 执行：llm_result 拍（有 tool）
Brain.Decide(llm_result, state) → call_tools_batch
Tool.Dispatch(...)
  Event.Append(tool.call_started)
  Event.Append(tool.execution_started)
  Event.Append(tool.execution_result)
Approval.Create(...)
Event.Append(tool.approval_required)
CommitStep(...) // 状态 waiting_human

// 用户审批
Approval.Decide(...)
Coordinator.RecordToolDecisions(...)
Event.Append(tool.approval_decided)
Coordinator.Enqueue(StepJob{Phase: human_approved})

// 执行：human_approved 拍
Tool.Dispatch(...)
Message.Insert(...)
Memory.IndexMessage(...)
Event.Append(tool.execution_result)
CommitStep(...) // 状态 running，投 tools_batch_result

// 执行：tools_batch_result 拍
Brain.Decide(tools_batch_result, state) → call_llm

// 用户取消
Run.Cancel(...)
CancelInFlight(...)
Event.Append(run.cancelled)
Session.ClearActiveRun(...)
Coordinator.DequeueNext(...)

// 继续 / 重试
Run.Continue(...)
Run.Retry(...)

// 打开会话或重连
Event.Subscribe(...)