agent_context

type AgentContext interface {
	// Load 检查并替换全部指令和历史；检查失败时保留原内容。
	Load(param *ContextLoadParam) error
	// AppendItems 检查并追加一批 Item，遇到摘要时裁剪已覆盖的历史；失败时保留原内容。
	AppendItems(items ...*defs.Item) error
	// BuildModelRequest 将指令、历史和工具组装成模型请求，补齐缺失的工具结果。
	// 模型不能看图时图片换成占位文字；能看图时只发送最近 20 张，更早的换成占位文字。
	BuildModelRequest(tools []llmkit.Tool) (request *llmkit.Request, inputThroughItemID defs.ItemID, err error)
	// GetMeasurement 返回本地估算、利用最近实际用量计算的预计占用和 Item 分项。
	GetMeasurement(tools []llmkit.Tool) (*ContextMeasurement, error)
	// RecordRequestUsage 替换最近完整普通调用的报告和实际思考模式。
	RecordRequestUsage(contextUsage *defs.TurnContextUsage)
	// GetCompactionSource 返回待压缩历史的副本，包含已有摘要；没有可压缩内容时返回 nil。
	// 自动压缩要求窗口已知且用量达到阈值；手动压缩不检查阈值。两者都按窗口的 20% 保留最近历史，
	// 保留范围覆盖全部原文时，自动压缩返回 nil，手动压缩返回全部历史。
	GetCompactionSource(measurement *ContextMeasurement, isManual bool) []*defs.Item
	// CompactHistory 调用摘要模型，填写 summary 并用它替换已覆盖的历史；失败时保留原上下文。
	// summary 由调用方创建，ContextSummary.CoveredThroughItemID 填 source 最后一条的 ID。
	// 发起过模型调用就返回 CompactionCall，调用失败也返回；组装请求失败、没有发起调用时返回 nil。
	CompactHistory(ctx context.Context, tools []llmkit.Tool, source []*defs.Item, summary *defs.Item) (*CompactionCall, error)
	// IsCompacted 当前历史是否以摘要开头？
	IsCompacted() bool
	// IsAgentsInstructionLoaded 当前历史里是否已有这个 Executor 下这个路径的目录规则？
	IsAgentsInstructionLoaded(executorID, path string) bool
}

type AgentContextOpt struct {
	// SessionID 标识本轮 Session，也用作 prompt_cache_key。
	SessionID defs.SessionID
	// TurnID 是摘要 Item 所属的 Turn。
	TurnID defs.TurnID
	Client llmkit.Client
	// Model 提供普通请求参数和窗口；自动压缩预留最大输出，窗口为 0 时不自动压缩。
	Model *defs.ModelDefinition
	// ReasoningEffort 是普通请求的推理强度，可以为空。
	ReasoningEffort string
	// CompactModel 提供摘要模型和它的默认推理强度。
	CompactModel *defs.ModelDefinition
}

type CompactionCall struct {
	ModelCallID defs.ModelCallID
	Usage       *defs.TokenUsage
}

type ContextCategory string

type ContextLoadParam struct {
	// System 是系统指令。
	System string
	// Items 是有序历史：最新摘要加上没被它覆盖的原文。
	Items []*defs.Item
	// ContextUsage 是最近完整普通调用的报告；为 nil 时仅本地计数。
	ContextUsage *defs.TurnContextUsage
}

type ContextMeasurement struct {
	// Model 是本次测量使用的模型，不依赖最近调用详情是否已加载。
	Model defs.ModelRef `json:"model"`
	// Window 是模型上下文窗口；0 表示窗口未知，此时不触发自动压缩。
	Window int `json:"window"`
	// ThresholdTokens 是预留最大输出后的自动压缩阈值；窗口未知时为 0。
	ThresholdTokens int `json:"threshold_tokens"`
	// RequestTokens 是利用最近实际用量和内容变化计算的预计占用；无适用报告时等于 EstimatedTokens。
	RequestTokens int `json:"request_tokens"`
	// EstimatedTokens 是未经校正的本地估算，等于 SystemTokens、ToolTokens 和 Items 各项 Tokens 之和。
	EstimatedTokens int `json:"estimated_tokens"`
	// IsUsageBased 本次预计占用是否使用了仍适用的模型上报用量？
	IsUsageBased bool `json:"is_usage_based"`
	// SystemTokens 是系统指令的估算用量。
	SystemTokens int `json:"system_tokens"`
	// ToolTokens 是工具定义的估算用量。
	ToolTokens int `json:"tool_tokens"`
	// Items 只含会发给模型的 Item，按上下文顺序排列。
	Items []ItemTokens `json:"items"`
}

type ItemTokens struct {
	ItemID   defs.ItemID     `json:"item_id"`
	TurnID   defs.TurnID     `json:"turn_id"`
	Category ContextCategory `json:"category"`
	Tokens   int             `json:"tokens"`
}