package engine

// query_chain.go - 查询链追踪(Query Chain Tracking).
//
// 精妙之处(CLEVER): 极简设计--只有 3 个字段,但足以追踪整条调用链.
// ChainId 标识"这是同一次用户请求引发的所有活动",
// Depth 标识"在调用链的第几层",
// ParentAgentId 标识"是谁 fork 的".
//
// 所有 Observer Event 自动带上这三个字段,BigQuery/Grafana 里可以:
//   - 按 ChainId 分组 → 看完整调用路径
//   - 按 Depth 统计 → 子 agent 嵌套深度
//   - 按 ChainId 汇总 token → 这条链总成本
//   - 按 ParentAgentId → 构建调用树
//
// 升华改进(ELEVATED): 比只有 chainId + depth 多了 ParentAgentId,支持构建完整调用树.
// 替代方案:只有 chainId + depth(原始设计,能分组但无法构建树).

import (
	"fmt"
	"math/rand"
	"time"
)

// QueryChainTracking 查询链追踪结构体.
type QueryChainTracking struct {
	// ChainId 整条链的唯一 ID(从用户请求到所有子 agent 共享同一个)
	ChainId string
	// Depth 当前深度(0=主查询, 1=子agent, 2=子子agent)
	Depth int
	// ParentAgentId 父 agent 的 ID(主查询为空)
	ParentAgentId string
}

// NewQueryChain 创建新的查询链(用户发消息时调用).
func NewQueryChain() *QueryChainTracking {
	return &QueryChainTracking{
		ChainId: generateChainId(),
		Depth:   0,
	}
}

// Fork 创建子链(SubAgent spawn 时调用).
// 继承 ChainId,Depth+1,记录 parentAgentId.
func (t *QueryChainTracking) Fork(parentAgentId string) *QueryChainTracking {
	return &QueryChainTracking{
		ChainId:       t.ChainId,
		Depth:         t.Depth + 1,
		ParentAgentId: parentAgentId,
	}
}

// EventFields 返回要注入到每个 Observer Event 的字段.
func (t *QueryChainTracking) EventFields() map[string]any {
	fields := map[string]any{
		"query_chain_id": t.ChainId,
		"query_depth":    t.Depth,
	}
	if t.ParentAgentId != "" {
		fields["parent_agent_id"] = t.ParentAgentId
	}
	return fields
}

// generateChainId 生成链 ID.
// 精妙之处(CLEVER): 用时间戳+随机数,比 UUID 更可读,方便日志追踪.
// 格式:"chain_1712345678_a1b2c3"
func generateChainId() string {
	const letters = "abcdefghijklmnopqrstuvwxyz0123456789"
	b := make([]byte, 6)
	for i := range b {
		b[i] = letters[rand.Intn(len(letters))]
	}
	return fmt.Sprintf("chain_%d_%s", time.Now().UnixMilli(), string(b))
}