// ContextBudget = 一次模型请求的上下文预算。
// 重点：输入不能把上下文窗口塞满，要给模型输出预留空间。
type ContextBudget = {
  maxInputTokens: number;        // 模型上下文窗口最大输入 token。
  reservedOutputTokens: number;  // 给模型回答预留的 token。
  systemTokens: number;          // system prompt 预计占用。
  memoryTokens: number;          // 记忆预计占用。
  historyTokens: number;         // 历史对话预计占用。
  retrievalTokens: number;       // 检索资料预计占用。
  toolResultTokens: number;      // 工具结果预计占用。
};

// getAvailableInputTokens = 当前真正可用于输入 messages 的 token。
function getAvailableInputTokens(budget: ContextBudget) {
  return budget.maxInputTokens - budget.reservedOutputTokens;
}

// buildContext = 上下文构建总入口。
// 它把 system、项目规则、记忆、检索、历史、当前用户输入拼成 messages。
export async function buildContext(input: BuildContextInput): Promise<Message[]> {
  // 根据模型上下文窗口创建预算。
  const budget = createBudget(input.model);

  // 每一块上下文都先抽象成 ContextPart，带优先级和 token 估算。
  const parts: ContextPart[] = [
    await systemPart(),
    await projectInstructionsPart(input.cwd),
    await memoryPart(input.userInput),
    await retrievalPart(input.userInput),
    await recentTranscriptPart(input.sessionId),
    currentUserPart(input.userInput)
  ];

  // 根据预算选择哪些块完整保留、哪些压缩、哪些丢弃。
  const selected = fitPartsIntoBudget(parts, budget);

  // 最终转成模型 messages。
  return selected.map(part => ({
    role: part.role,
    content: part.content
  }));
}

// ContextPart = 一个可独立选择/压缩的上下文块。
// 例如 system rules、memory、retrieved docs、recent transcript 都是 part。
type ContextPart = {
  name: string; // 块名称，例如 "memory"、"retrieval"。
  role: "system" | "user" | "assistant" | "tool"; // 放进 messages 时的 role。
  priority: number; // 数字越小优先级越高，越不能丢。
  content: string; // 这块上下文正文。
  estimatedTokens: number; // 估算 token，用于预算选择。
  compressible: boolean; // 超预算时是否允许摘要压缩。
};

// fitPartsIntoBudget = 在预算内选择上下文块。
// 策略：先按优先级选，高优先级保留；低优先级必要时压缩或丢弃。
function fitPartsIntoBudget(parts: ContextPart[], budget: ContextBudget) {
  // 计算输入可用 token。
  const max = getAvailableInputTokens(budget);

  // 按 priority 排序，P0/P1 先处理。
  const sorted = [...parts].sort((a, b) => a.priority - b.priority);

  const selected: ContextPart[] = [];
  let used = 0;

  for (const part of sorted) {
    // 如果完整放得下，直接保留。
    if (used + part.estimatedTokens <= max) {
      selected.push(part);
      used += part.estimatedTokens;
      continue;
    }

    // 如果放不下但允许压缩，就尝试压缩到剩余预算内。
    if (part.compressible) {
      const compressed = compressPartToFit(part, max - used);
      if (compressed) {
        selected.push(compressed);
        used += compressed.estimatedTokens;
      }
    }
  }

  // 选择时按优先级，但输出 messages 时要恢复合理顺序。
  // 例如 system 仍然要在 user 前面。
  return selected.sort((a, b) => originalOrder(a.name) - originalOrder(b.name));
}

// estimateTokens = 粗略 token 估算。
// 中文/英文/tokenizer 差异很大，这只是入门兜底。
function estimateTokens(text: string) {
  return Math.ceil(text.length / 2);
}

// projectInstructionsPart = 读取项目规则文件。
// 这些规则会影响 Agent 如何读写代码，所以优先级高。
async function projectInstructionsPart(cwd: string): Promise<ContextPart> {
  // 常见项目规则来源。
  const candidates = ["AGENTS.md", "CLAUDE.md", "README.md"];
  const chunks: string[] = [];

  for (const file of candidates) {
    // 文件不存在就跳过。
    const content = await readFileIfExists(resolve(cwd, file));
    if (content) {
      // 每个规则文件都限长，防止 README 巨大。
      chunks.push(`# ${file}\n${content.slice(0, 12_000)}`);
    }
  }

  const content = chunks.join("\n\n");

  return {
    name: "project_instructions",
    role: "system",
    priority: 1,
    content,
    estimatedTokens: estimateTokens(content),
    compressible: true
  };
}

// Memory = 长期记忆的一条记录。
// 记忆不是聊天历史，而是跨任务可复用的稳定事实/偏好/决策。
type Memory = {
  id: string; // 记忆 ID。
  scope: "user" | "project"; // 用户级还是项目级。
  type: "preference" | "fact" | "decision" | "todo"; // 记忆类型。
  content: string; // 记忆正文。
  updatedAt: string; // 更新时间，用于排序和淘汰旧信息。
};

// memoryPart = 选出与当前任务相关的记忆，拼成上下文块。
async function memoryPart(userInput: string): Promise<ContextPart> {
  // 加载所有记忆，但不会全量塞给模型。
  const memories = await loadAllMemory();

  // 按相关性排序，只取前 12 条。
  const ranked = rankMemory(memories, userInput).slice(0, 12);

  // 带上 type，模型能区分偏好、事实、决策、任务项。
  const content = ranked
    .map(memory => `- [${memory.type}] ${memory.content}`)
    .join("\n");

  return {
    name: "memory",
    role: "system",
    priority: 2,
    content: `Relevant long-term memory:\n${content}`,
    estimatedTokens: estimateTokens(content),
    compressible: true
  };
}

// rankMemory = 入门版记忆相关性排序。
// 用查询词和记忆内容的词重叠数打分。
function rankMemory(memories: Memory[], query: string) {
  // 把用户输入切词成集合。
  const words = new Set(query.toLowerCase().split(/\s+/));

  return memories
    .map(memory => ({
      memory,
      // 统计 memory.content 中有多少词出现在 query 里。
      score: memory.content
        .toLowerCase()
        .split(/\s+/)
        .filter(word => words.has(word)).length
    }))
    // 分数高的排前面。
    .sort((a, b) => b.score - a.score)
    .map(item => item.memory);
}

// recentTranscriptPart = 构建会话历史上下文块。
// 策略：最近消息原文保留，更早历史压成 summary。
async function recentTranscriptPart(sessionId: string): Promise<ContextPart> {
  // 读取完整会话记录。
  const transcript = await loadTranscript(sessionId);

  // 最近 12 条保留原文，保证连续性。
  const recent = transcript.slice(-12);

  // 更早的消息进入摘要。
  const older = transcript.slice(0, -12);

  // 如果有旧消息，加载或创建摘要。
  const summary = older.length
    ? await loadOrCreateSummary(sessionId, older)
    : "";

  const content = [
    summary ? `Previous summary:\n${summary}` : "",
    `Recent messages:\n${formatMessages(recent)}`
  ].filter(Boolean).join("\n\n");

  return {
    name: "transcript",
    role: "system",
    priority: 3,
    content,
    estimatedTokens: estimateTokens(content),
    compressible: true
  };
}

Summarize the previous agent session for continuation.

Keep:
1. User's goal.
2. Files inspected.
3. Files modified.
4. Commands run and meaningful results.
5. Decisions made.
6. Failed attempts and why they failed.
7. Current next step.

Drop:
1. Chit-chat.
2. Repeated logs.
3. Full command output unless essential.
4. Outdated speculation.

// formatToolResult = 控制工具结果放进上下文的长度。
// 工具输出很容易超长，例如 grep、test、日志。
function formatToolResult(result: ToolResult) {
  const max = 16_000;

  // 不超限就原样返回。
  if (result.content.length <= max) {
    return result.content;
  }

  // 超限时截断，并附上 summary 告诉模型这不是完整输出。
  return [
    result.content.slice(0, max),
    `\n[Tool output truncated. Summary: ${result.summary}]`
  ].join("");
}

// RetrievedChunk = RAG 检索出来的一段资料。
// 必须保留来源，否则模型回答无法追溯。
type RetrievedChunk = {
  sourcePath: string; // 来源文件路径。
  titlePath: string;  // 文档标题路径或层级标题。
  content: string;    // 片段正文。
  score: number;      // 检索相关性分数。
};

// formatRetrievedChunks = 把 RAG 片段格式化给模型。
function formatRetrievedChunks(chunks: RetrievedChunk[]) {
  return chunks.map((chunk, index) => `
[Source ${index + 1}]
path: ${chunk.sourcePath}
title: ${chunk.titlePath}
score: ${chunk.score}
content:
${chunk.content}
`).join("\n");
}

Answer using the provided sources.
If the sources do not contain the answer, say you are not sure.
Cite source paths when making factual claims.

// saveContextDebug = 保存最终发给模型的 messages。
// 它是排查“模型到底看到了什么”的关键工具。
async function saveContextDebug(sessionId: string, messages: Message[]) {
  await writeFile(
    `.agent/debug/${sessionId}-context.json`,
    JSON.stringify(messages, null, 2),
    "utf8"
  );
}

// selectMemories = 从长期记忆里选出本轮真正该给模型看的部分。
function selectMemories(memories: MemoryRecord[], task: TaskContext) {
  return memories
    .filter(m => m.scope === "global" || m.scope === task.projectId) // 不跨项目乱带
    .filter(m => !m.expiresAt || m.expiresAt > task.now)             // 过期记忆不进上下文
    .map(m => ({
      memory: m,
      score: relevance(m, task) + recencyBoost(m) + confidenceBoost(m)
    }))
    .filter(item => item.score >= task.memoryThreshold)
    .sort((a, b) => b.score - a.score)
    .slice(0, task.maxMemories)
    .map(item => item.memory);
}

type ContextPacket = {
  id: string;
  content: string;
  sourceType: "system" | "task" | "history" | "rag" | "memory" | "tool";
  sourceId: string;
  tokenCount: number;
  priority: number;
  relevance: number;
  timestamp?: string;
  selectedReason?: string;
  dropReason?: string;
};