agent

type Agent interface {
	// Run 循环调用模型、执行工具，直到模型不再调用工具且没有新的补充输入；IsCompactOnly 时只压缩上下文。每个实例只 Run 一次。
	// events 非 nil 时调用方要一直读到通道关闭，Run 返回前关闭它；取消后仍会发完剩余事件。
	// 临时模型错误自动重试；失败尝试的输出留在草稿和事件里，只有成功调用的输出加入上下文、执行工具。
	Run(ctx context.Context, events chan<- *AgentEvent) (AgentResult, error)
}

type AgentDefinition struct {
	// Name 是角色名，对应 Session.AgentName。
	Name string
	// Description 说明这个角色适合处理的任务。
	Description string
	// Instructions 是这个角色的系统指令。
	Instructions string
	// Model 是本角色新建 Session 的默认模型；Session 可以改选其他模型。
	Model defs.ModelRef
	// CompactModel 是生成上下文摘要使用的模型；零值表示使用本轮模型。
	CompactModel defs.ModelRef
	// ToolNames 是可用的普通工具名；为空时可用工具目录中的全部工具，协作工具始终可用。
	ToolNames []string
	// SkillNames 是可用的 skill 名；为空时可用 skill 目录中的全部 skill。
	SkillNames []string
	// MCPServerIDs 是可用的 MCP server id；nil 表示全部可用，[] 表示不用 MCP。
	MCPServerIDs defs.OptionalStringList
}

type AgentEvent struct {
	Type AgentEventType `json:"type"`
	// ItemIndex 是 Item 在本次 Run 输出中的位置；ContextMeasured、ModelCallFinished 和 HookRun 不对应 Item，不用它。
	ItemIndex int `json:"item_index"`
	// Item 是开始、完成和中断事件携带的完整 Item 副本，增量事件不带。
	// 中断事件的 Item 是要保存的内容，为 nil 时这个位置不用保存（例如没有文字的中断消息草稿）。
	// ToolCall 的完成事件只说明参数已完整，工具还没执行。
	Item *defs.Item `json:"item,omitempty"`
	// Delta 是增量事件携带的追加内容。
	Delta *AgentItemDelta `json:"delta,omitempty"`
	// ToolProgress 是 ToolProgress 事件携带的工具输出。
	ToolProgress *AgentToolProgress `json:"tool_progress,omitempty"`
	// Measurement 是 ContextMeasured 事件携带的上下文用量。
	Measurement *agent_context.ContextMeasurement `json:"measurement,omitempty"`
	// ModelCall 是 ModelCallFinished 事件携带的调用结果。
	ModelCall *AgentModelCall `json:"model_call,omitempty"`
	// HookRun 是 HookRun 事件携带的运行记录。
	HookRun *defs.HookRun `json:"hook_run,omitempty"`
}

type AgentEventType string

type AgentInputRequest struct {
	// FinishIfEmpty 没有补充输入时是否让 Session 停止向本轮投递？Agent 准备结束本轮时为 true。
	FinishIfEmpty bool
	// Reply 接收 Turn 的回复，Turn 回复后关闭它。
	Reply chan<- AgentInputResult
}

type AgentInputResult struct {
	Items []*defs.Item
	Err   error
}

type AgentItemDelta struct {
	// Text 是追加到消息的文本。
	Text string `json:"text,omitempty"`
	// ReasoningSummary 是追加的推理摘要片段。
	ReasoningSummary []string `json:"summary,omitempty"`
	// ReasoningContent 是追加的推理内容片段。
	ReasoningContent []string `json:"content,omitempty"`
	// Arguments 是追加的工具参数。
	Arguments string `json:"arguments,omitempty"`
}

type AgentModelCall struct {
	ModelCallID defs.ModelCallID `json:"model_call_id"`
	Purpose     ModelCallPurpose `json:"purpose"`
	Usage       *defs.TokenUsage `json:"usage,omitempty"`
	// ContextUsage 只在普通调用正常结束时填写，Context 和 Turn 用同一份。
	ContextUsage *defs.TurnContextUsage `json:"context_usage,omitempty"`
}

type AgentOpt struct {
	TurnID    defs.TurnID
	SessionID defs.SessionID
	Client    llmkit.Client
	// Model 提供本轮请求目标和消息角色合并选项。
	Model *defs.ModelDefinition
	// Context 保存本轮指令和历史，组装模型请求。
	Context agent_context.AgentContext
	// ToolExecutor 列出本轮工具并执行工具调用；nil 表示没有工具。
	ToolExecutor executor.ToolExecutor
	// Environments 保存本对话的执行环境；第一个是默认环境，提供目录规则和 Stop hook 的工作区。
	Environments []executor.ExecutionEnvironment
	// InputRequests 向 Turn 请求补充输入；nil 时不读补充输入。
	InputRequests chan<- AgentInputRequest
	// IsCompactOnly 这个 Agent 是否只压缩上下文？是的话 Run 只把历史压成摘要就返回，不调用普通模型。
	IsCompactOnly bool
	// Hooks 在模型这一步没有工具调用时触发 Stop 或 SubagentStop；为 nil 或 Environments 为空时不触发。
	Hooks hook.Hooks
	// Session 是本 Agent 运行所在的 Session，随 hook 事件交给脚本；ParentSessionID 非空表示子 Session，触发 SubagentStop。
	Session defs.Session
}

type AgentResult struct {
	// Items 是本轮全部草稿，包括失败尝试的输出。
	Items []*defs.Item
	// FinalModelCallID 是最后一次成功的普通模型调用；Run 失败或只压缩时为空。
	FinalModelCallID defs.ModelCallID
	// Stats 是本次运行（一个 Turn）的统计，Turn 据此写遥测小结。
	Stats AgentStats
}

type AgentStats struct {
	// Steps 是普通模型调用次数，包含失败和重试。
	Steps int
	// InferenceCalls 是普通模型和摘要模型的调用总次数，包含失败和重试。
	InferenceCalls int
	// ToolCalls 是收到的工具结果数，包含没能分发、直接返回错误的调用。
	ToolCalls int
	// FailedToolCalls 是其中带错误的工具结果数。
	FailedToolCalls int
	// Usage 是全部模型调用的 token 合计。
	Usage defs.TokenUsage
	// FinishReason 是最后一次普通模型调用的结束原因，已换成遥测取值；这次调用失败或被取消、又没收到结束原因时为 error。
	FinishReason string
}

type AgentToolProgress struct {
	// CallID 是对应工具调用的 CallID，可以关联执行前已保存的 ToolCall。
	CallID string `json:"call_id"`
	// Stream 是这段输出所属的流类别。
	Stream executor.ExecutionStreamType `json:"stream"`
	// Content 是这段输出的 JSON 内容。
	Content json.RawMessage `json:"content"`
}

type ModelCallPurpose string