#Step 12 — 종합 프로젝트: 딥 리서치 에이전트

export interface CorpusDoc {
  url: string;
  title: string;
  topic: "general" | "news" | "finance";
  content: string;
}

export const MOCK_CORPUS: CorpusDoc[] = [
  {
    url: "https://example.com/docs/rag-overview",
    title: "RAG(검색 증강 생성) 개요",
    topic: "general",
    content: "...",
  },
  // ... 총 6개
];

function scoreDoc(queryTokens: string[], doc: CorpusDoc): number {
  const title = doc.title.toLowerCase();
  const content = doc.content.toLowerCase();
  let score = 0;
  for (const t of queryTokens) {
    if (title.includes(t)) score += 3;
    if (content.includes(t)) score += 1;
  }
  return score;
}

import { tool } from "langchain";
import * as z from "zod";

export const mockSearch = tool(
  async ({ query, maxResults = 3, topic = "general" }) => {
    const tokens = tokenize(query);
    const pool =
      topic === "general" ? MOCK_CORPUS : MOCK_CORPUS.filter((d) => d.topic === topic);

    const hits = pool
      .map((doc) => ({ doc, score: scoreDoc(tokens, doc) }))
      .filter((x) => x.score > 0)
      .sort((a, b) => b.score - a.score)
      .slice(0, maxResults)
      .map(({ doc }) => ({ url: doc.url, title: doc.title, content: doc.content }));

    return formatHits(query, hits);
  },
  {
    name: "web_search",
    description:
      "웹에서 주제에 대한 정보를 검색합니다. 관련 문서의 제목, URL, 본문을 돌려줍니다. " +
      "사실 확인이 필요한 모든 주장에 대해 호출하세요.",
    schema: z.object({
      query: z.string().describe("검색어. 구체적이고 서술적으로 작성하세요."),
      maxResults: z.number().optional().describe("돌려받을 최대 결과 수 (기본 3)"),
      topic: z
        .enum(["general", "news", "finance"])
        .optional()
        .describe("주제 필터. 'general'(기본) / 'news'(시사) / 'finance'(금융)"),
    }),
  },
);

export function formatHits(query: string, hits: SearchHit[]): string {
  if (hits.length === 0) {
    return `'${query}' 에 대한 검색 결과가 없습니다. 다른 키워드로 다시 시도하세요.`;
  }
  const body = hits
    .map(
      (h, i) =>
        `## [결과 ${i + 1}] ${h.title}\n**URL:** ${h.url}\n\n${h.content}\n\n---`,
    )
    .join("\n");
  return `'${query}' 에 대해 ${hits.length}건을 찾았습니다:\n\n${body}`;
}

export const tavilySearch = tool(
  async ({ query, maxResults = 3, topic = "general" }) => {
    const apiKey = process.env.TAVILY_API_KEY;
    if (!apiKey) {
      return "TAVILY_API_KEY 가 설정되지 않아 검색할 수 없습니다.";
    }
    try {
      const response = await fetch("https://api.tavily.com/search", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${apiKey}`,
        },
        body: JSON.stringify({ query, max_results: maxResults, topic }),
      });
      if (!response.ok) {
        return `검색 실패: Tavily HTTP ${response.status}`;
      }
      const data = (await response.json()) as {
        results?: Array<{ url: string; title: string }>;
      };
      const results = data.results ?? [];

      const hits: SearchHit[] = await Promise.all(
        results.map(async (r) => ({
          url: r.url,
          title: r.title,
          content: await fetchWebpageContent(r.url),
        })),
      );
      return formatHits(query, hits);
    } catch (e) {
      return `검색 실패: ${String(e)}`;
    }
  },
  {
    name: "web_search", // ← 목과 완전히 같은 이름
    description: "...", // ← 목과 완전히 같은 설명
    schema: z.object({ /* ← 목과 완전히 같은 스키마 */ }),
  },
);

async function fetchWebpageContent(url: string, timeoutMs = 10_000): Promise<string> {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), timeoutMs);
  try {
    const response = await fetch(url, {
      headers: { "User-Agent": "Mozilla/5.0 ..." },
      signal: controller.signal,
    });
    if (!response.ok) {
      return `(${url} 을 가져오지 못했습니다: HTTP ${response.status})`;
    }
    const text = await response.text();
    return text.slice(0, 8_000);  // 본문을 통째로 넣으면 토큰이 터집니다
  } catch (e) {
    return `(${url} 을 가져오지 못했습니다: ${String(e)})`;
  } finally {
    clearTimeout(timer);
  }
}

export function createSearchTool() {
  return process.env.TAVILY_API_KEY ? tavilySearch : mockSearch;
}

export const ORCHESTRATOR_MODEL =
  process.env.ORCHESTRATOR_MODEL ?? "anthropic:claude-sonnet-4-6";

export const RESEARCH_MODEL =
  process.env.RESEARCH_MODEL ?? "anthropic:claude-haiku-4-5";

export const CRITIQUE_MODEL = process.env.CRITIQUE_MODEL ?? RESEARCH_MODEL;

import type { SubAgent } from "deepagents";

export const researchSubagent: SubAgent = {
  name: "research-subagent",
  description:
    "웹 검색으로 하나의 구체적인 주제를 깊이 조사하고, 결과를 /findings/ 에 저장한 뒤 요약을 돌려줍니다. " +
    "한 번에 하나의 주제만 주세요. 배경 설명을 포함해 자기완결적으로 지시해야 합니다.",
  systemPrompt: RESEARCHER_PROMPT,
  tools: [createSearchTool()],
  model: RESEARCH_MODEL,
};

export const critiqueSubagent: SubAgent = {
  name: "critique-subagent",
  description:
    "/findings/ 의 조사 결과를 심사해 PASS 또는 REVISE 를 판정합니다. 검색은 하지 않습니다. " +
    "인용 누락, 출처 유령, 질문 미달, 근거 빈약, 모순을 찾아냅니다. 조사가 끝난 뒤 호출하세요.",
  systemPrompt: CRITIQUE_PROMPT,
  model: CRITIQUE_MODEL,
};

export function readStateFile(
  files: Record<string, unknown> | undefined,
  path: string,
): string | undefined {
  const entry = files?.[path] as { content?: unknown } | undefined;
  if (!entry) return undefined;

  const content = entry.content;
  if (typeof content === "string") return content;              // v2 텍스트
  if (Array.isArray(content)) return content.join("\n");        // v1 줄 배열
  if (content instanceof Uint8Array) {
    return new TextDecoder().decode(content);                   // v2 바이너리
  }
  return undefined;
}

interface FileDataV1 {
  content: string[];        // 줄 배열
  created_at: string;
  modified_at: string;
}

interface FileDataV2 {
  content: string | Uint8Array;   // 텍스트 또는 바이너리
  // ... mime_type 등
}

createDeepAgent({
  systemPrompt: "내 프롬프트",  // → "내 프롬프트" + 내장 기본 프롬프트
});

createDeepAgent({
  systemPrompt: {
    prefix: "앞에 붙일 것",
    base: null,          // ← 내장 기본 프롬프트 제거
    suffix: "뒤에 붙일 것",
  },
});

export const TODAY = new Date().toISOString().split("T")[0];

export const ORCHESTRATOR_PROMPT = `당신은 딥 리서치 오케스트레이터입니다. 오늘 날짜는 ${TODAY} 입니다.

당신의 역할은 **직접 조사하는 것이 아니라, 조사를 지휘하고 결과를 종합하는 것**입니다.
당신에게는 web_search 도구가 없습니다. 모든 조사는 task() 로 서브에이전트에게 위임하세요.

# 작업 절차

아래 순서를 반드시 지키세요.

1. **질문 저장**: write_file 로 사용자의 원래 질문을 \`/question.txt\` 에 그대로 저장합니다.
   나중에 "내가 무슨 질문에 답하고 있었지?"를 확인하는 기준점이 됩니다.
2. **계획**: write_todos 로 리서치 단계를 3~6개의 할 일로 쪼갭니다.
   할 일은 "무엇을 알아낼 것인가"로 쓰세요. "검색한다" 같은 행위가 아니라 "X의 비용 구조를 파악한다" 처럼.
3. **조사 위임**: task() 로 research-subagent 를 호출합니다.
   - 서브에이전트에게는 **한 번에 하나의 구체적인 주제**만 줍니다.
   - 서브에이전트는 당신의 대화 내용을 볼 수 없습니다. 배경을 포함해 **자기완결적으로** 지시하세요.
     나쁜 예: "그것에 대해 더 조사해줘"
     좋은 예: "RAG(검색 증강 생성)의 추론 비용 구조를 조사해라. 특히 토큰 오버헤드와 절감 기법을 다뤄라."
   - 조사 결과는 write_file 로 \`/findings/<주제-슬러그>.md\` 에 저장하라고 지시하세요.
4. **비평**: 조사가 끝나면 task() 로 critique-subagent 를 호출해 \`/findings/\` 를 검토시킵니다.
   비평이 지적한 구멍은 다시 research-subagent 에게 보내 메웁니다.
5. **보고서 작성**: 모든 findings 를 read_file 로 읽고 종합해 \`/report.md\` 에 씁니다.
6. **검증**: \`/question.txt\` 를 다시 읽고, 보고서가 질문의 모든 측면에 답했는지 확인합니다.

# 위임 전략

- **기본은 서브에이전트 1개**입니다. 단순 질문을 여러 개로 쪼개면 토큰만 낭비됩니다.
  "X가 무엇인가" → 1개.
- **명시적 비교나 독립된 축이 있을 때만 병렬로** 나눕니다.
  "A와 B를 비교하라" → A 담당 1개 + B 담당 1개.
  "유럽/아시아/북미의 현황" → 지역별 3개.
- 한 번에 최대 3개까지만 병렬로 띄우세요. 병렬 실행은 한 응답에서 task() 를 여러 번 호출하면 됩니다.
- 위임 라운드는 최대 3회입니다. 그 안에 충분한 근거를 못 모았으면, 모은 것으로 답하고
  보고서에 "무엇을 확인하지 못했는지" 한계를 명시하세요.

# 보고서 작성 규칙

\`/report.md\` 는 다음을 지킵니다.

- 구조: 비교 질문이면 (도입 → A 개요 → B 개요 → 상세 비교 → 결론).
  개요 질문이면 (개요 → 핵심 개념들 → 결론). 목록 질문이면 도입 없이 바로 항목 나열.
- 문체: **평서문, 문단 중심**으로 씁니다. 불릿만 나열하지 마세요.
- 자기 지칭 금지: "제가 조사한 결과", "찾아보니" 같은 표현을 쓰지 마세요.
  보고서는 리서처의 일기가 아니라 **문서**입니다.
- 섹션 제목은 \`##\`, 하위는 \`###\` 를 씁니다.

# 인용 규칙 (엄격)

- 모든 사실 주장 뒤에 \`[1]\`, \`[2]\` 형식으로 출처 번호를 답니다.
- **번호는 URL 단위로 전역에서 유일**해야 합니다. 서로 다른 findings 파일이 같은 URL 을 쓰면 같은 번호를 씁니다.
- 보고서 맨 끝에 \`### 출처\` 섹션을 만들고, 번호 순서대로 빠짐없이(1,2,3...) 나열합니다.
- 형식: \`[1] 문서 제목: URL\` — 한 줄에 하나씩.
- **findings 에 없는 URL 을 지어내지 마세요.** 출처가 없는 주장은 아예 쓰지 마세요.

# 절대 규칙

- 당신은 web_search 를 갖고 있지 않습니다. 조사는 반드시 위임하세요.
- findings 에 근거가 없는 내용을 보고서에 쓰지 마세요. 모르면 "확인되지 않음"이라고 쓰세요.
- 최종 보고서는 반드시 \`/report.md\` 에 write_file 로 저장하세요. 채팅 답변으로만 끝내지 마세요.`;

export const TODAY = new Date().toISOString().split("T")[0];

export function buildResearchAgent(options: BuildOptions = {}) {
  const { requireApproval = false } = options;

  const checkpointer = requireApproval ? new MemorySaver() : undefined;

  return createDeepAgent({
    model: ORCHESTRATOR_MODEL,
    systemPrompt: ORCHESTRATOR_PROMPT,
    tools: [],
    subagents: allSubagents,
    checkpointer,
    interruptOn: requireApproval
      ? {
          write_file: {
            allowedDecisions: ["approve", "edit", "reject"],
            when: (request) =>
              String(request.toolCall.args.file_path ?? "") === "/report.md",
          },
        }
      : undefined,
  });
}

const checkpointer = requireApproval ? new MemorySaver() : undefined;

const config = { configurable: { thread_id: crypto.randomUUID() } };

let result = await agent.invoke(input, { ...config, recursionLimit: 100 });

while (requireApproval && "__interrupt__" in result) {
  const interrupts = (result as Record<string, unknown>)["__interrupt__"] as Array<{
    value?: unknown;
  }>;

  const payload = interrupts?.[0]?.value as
    | { actionRequests?: Array<{ name: string; args: Record<string, unknown> }> }
    | undefined;
  const action = payload?.actionRequests?.[0];

  const draft = String(action?.args?.content ?? "");
  console.log(draft.slice(0, 1_500));

  const rl = readline.createInterface({ input: stdin, output: stdout });
  const answer = (await rl.question("승인하시겠습니까? [y=승인 / n=거절] : "))
    .trim()
    .toLowerCase();
  rl.close();

  if (answer === "y") {
    result = await agent.invoke(
      new Command({ resume: { decisions: [{ type: "approve" }] } }),
      { ...config, recursionLimit: 100 },
    );
  } else {
    // ... 거절 사유를 받아서
    result = await agent.invoke(
      new Command({ resume: { decisions: [{ type: "reject", message: reason }] } }),
      { ...config, recursionLimit: 100 },
    );
  }
}

let result = await agent.invoke(input, { ...config, recursionLimit: 100 });

const messages = result.messages ?? [];
let inputTokens = 0;
let outputTokens = 0;
for (const m of messages) {
  const usage = (m as unknown as { usage_metadata?: unknown }).usage_metadata as
    | { input_tokens?: number; output_tokens?: number }
    | undefined;
  if (usage) {
    inputTokens += usage.input_tokens ?? 0;
    outputTokens += usage.output_tokens ?? 0;
  }
}

/**
 * Step 12 — 종합 프로젝트: 딥 리서치 에이전트
 * 목(mock) 검색용 오프라인 코퍼스.
 *
 * API 키 없이도 코스를 실습할 수 있도록, 검색 도구가 돌려줄 문서를 여기에 하드코딩했습니다.
 * 문서 주제는 "RAG vs 파인튜닝"입니다 — deepagents 공식 문서의 딥 리서치 예제가 쓰는
 * 기본 질문("What are the main differences between RAG and fine-tuning?")과 맞춰 두었습니다.
 *
 * 주의: 이 코퍼스의 내용은 **교육용으로 작성한 요약문**입니다. 실제 논문/기사 원문이 아니며,
 * URL 도 실재하지 않는 예시용입니다(example.com). 진짜 웹 검색은 tools.ts 의 Tavily 도구를 쓰세요.
 */

export interface CorpusDoc {
  url: string;
  title: string;
  /** 검색 topic 필터와 대응 */
  topic: "general" | "news" | "finance";
  /** 본문 (마크다운) */
  content: string;
}

export const MOCK_CORPUS: CorpusDoc[] = [
  {
    url: "https://example.com/docs/rag-overview",
    title: "RAG(검색 증강 생성) 개요",
    topic: "general",
    content: [
      "RAG(Retrieval-Augmented Generation, 검색 증강 생성)는 모델의 가중치를 바꾸지 않고,",
      "질문과 관련된 문서를 외부 저장소에서 검색해 프롬프트에 끼워 넣는 방식이다.",
      "",
      "핵심 구성요소는 세 가지다.",
      "1) 인덱싱: 문서를 청크로 쪼개고 임베딩해 벡터 DB에 저장한다.",
      "2) 검색: 질문을 임베딩해 유사한 청크 상위 k개를 가져온다.",
      "3) 생성: 가져온 청크를 컨텍스트로 붙여 모델에게 답을 쓰게 한다.",
      "",
      "장점: 지식을 즉시 갱신할 수 있다. 문서를 하나 추가하면 그 순간부터 반영된다.",
      "출처(citation)를 답변에 붙일 수 있어 검증이 가능하다. 초기 구축 비용이 파인튜닝보다 낮다.",
      "",
      "단점: 검색이 실패하면 답도 실패한다(garbage in, garbage out).",
      "매 호출마다 검색된 문서가 입력 토큰에 더해지므로 추론 비용과 지연시간이 늘어난다.",
      "모델의 '말투'나 '출력 형식' 자체를 바꾸는 데는 효과가 제한적이다.",
    ].join("\n"),
  },
  {
    url: "https://example.com/docs/fine-tuning-overview",
    title: "파인튜닝(Fine-tuning) 개요",
    topic: "general",
    content: [
      "파인튜닝은 사전학습된 모델의 가중치를 추가 데이터로 더 학습시켜 바꾸는 방법이다.",
      "",
      "대표 기법:",
      "- 전체 파인튜닝(full fine-tuning): 모든 파라미터를 갱신. 비용이 가장 크다.",
      "- LoRA/QLoRA 같은 PEFT(Parameter-Efficient Fine-Tuning): 소수의 어댑터 파라미터만 학습.",
      "  전체 대비 GPU 메모리를 크게 줄이면서 비슷한 성능을 낸다. 현재 실무의 기본 선택지다.",
      "",
      "장점: 출력 형식, 말투, 도메인 전문 용어를 모델에 '내재화'할 수 있다.",
      "프롬프트에 예시를 길게 넣지 않아도 되므로 추론 시 입력 토큰이 짧아진다.",
      "특정 좁은 작업에서는 프롬프팅보다 정확도가 높다.",
      "",
      "단점: 지식 갱신이 느리다. 새 사실을 넣으려면 데이터셋을 다시 만들고 다시 학습해야 한다.",
      "학습 데이터 준비가 가장 큰 비용이다(수백~수천 개의 고품질 예시).",
      "환각(hallucination)을 줄여주지 않는다 — 오히려 모르는 걸 자신 있게 말하도록 학습될 수 있다.",
      "출처를 댈 수 없다.",
    ].join("\n"),
  },
  {
    url: "https://example.com/blog/rag-vs-finetuning-decision",
    title: "RAG와 파인튜닝, 무엇을 언제 쓰나 — 의사결정 가이드",
    topic: "general",
    content: [
      "둘은 경쟁 관계가 아니라 서로 다른 문제를 푼다. 한 문장으로 요약하면:",
      "**RAG는 모델이 '무엇을 아는가'를 바꾸고, 파인튜닝은 '어떻게 행동하는가'를 바꾼다.**",
      "",
      "| 기준 | RAG | 파인튜닝 |",
      "| --- | --- | --- |",
      "| 지식 갱신 | 문서 추가로 즉시 | 재학습 필요 |",
      "| 출처 제시 | 가능 | 불가능 |",
      "| 출력 형식/말투 제어 | 약함 | 강함 |",
      "| 추론 비용 | 높음(문서가 입력에 붙음) | 낮음 |",
      "| 초기 비용 | 낮음 | 높음(데이터셋 구축) |",
      "| 환각 감소 | 도움 됨(근거 제공) | 도움 안 됨 |",
      "",
      "실무 권장 순서:",
      "1. 프롬프팅으로 먼저 시도한다. 놀랍게도 여기서 끝나는 경우가 많다.",
      "2. 사실 정확도가 문제면 RAG를 붙인다.",
      "3. 형식/말투가 문제면 파인튜닝을 한다.",
      "4. 둘 다 문제면 둘 다 한다 — 파인튜닝한 모델에 RAG를 얹는 조합이 실제로 가장 강력하다.",
      "",
      "흔한 실수: '모델이 환각을 일으키니 파인튜닝하자'는 잘못된 처방이다. 환각의 원인이",
      "지식 부족이라면 답은 RAG다.",
    ].join("\n"),
  },
  {
    url: "https://example.com/research/rag-cost-analysis",
    title: "RAG 시스템의 비용 구조 분석",
    topic: "finance",
    content: [
      "RAG의 비용은 크게 인덱싱 비용과 추론 비용으로 나뉜다.",
      "",
      "인덱싱(1회성): 문서 임베딩 비용. 100만 토큰 문서를 임베딩하는 데 드는 비용은",
      "일반적으로 몇 달러 수준으로, 파인튜닝 대비 무시할 만하다.",
      "",
      "추론(반복): 이게 진짜 비용이다. 매 질문마다 검색된 청크 k개가 입력 토큰에 더해진다.",
      "k=5, 청크당 500토큰이면 질문마다 2,500토큰이 추가된다. 하루 10만 질문이면",
      "2.5억 입력 토큰이 순수 오버헤드로 발생한다.",
      "",
      "비용 절감 기법:",
      "- 프롬프트 캐싱: 반복되는 시스템 프롬프트/문서 부분을 캐시해 입력 비용을 크게 낮춘다.",
      "- 리랭킹 후 k 줄이기: k=20으로 검색한 뒤 리랭커로 상위 3개만 남기면 품질은 유지하면서 토큰이 준다.",
      "- 작은 모델로 라우팅: 쉬운 질문은 저가 모델로 보낸다.",
      "",
      "파인튜닝 비용: 학습 자체보다 **데이터셋 구축 인건비**가 지배적이다. 고품질 예시 1,000개를",
      "사람이 만들면 수 주가 걸린다. 학습 비용은 LoRA 기준 수십 달러로 오히려 저렴한 편이다.",
    ].join("\n"),
  },
  {
    url: "https://example.com/news/hybrid-approach-2026",
    title: "2026년 현장 보고: 하이브리드 접근이 표준이 되다",
    topic: "news",
    content: [
      "최근 프로덕션 LLM 시스템을 운영하는 팀들을 조사한 결과, 단일 기법만 쓰는 곳은 소수였다.",
      "",
      "가장 흔한 조합은 다음과 같다.",
      "- 베이스 모델 + RAG: 가장 흔하다. 구축이 빠르고 지식 갱신이 쉽다.",
      "- 파인튜닝 모델 + RAG: 도메인 말투가 중요한 곳(법률, 의료, 고객지원)에서 쓴다.",
      "  파인튜닝으로 형식을 잡고, RAG로 최신 사실을 공급한다.",
      "- 파인튜닝만: 출력 스키마가 고정된 분류/추출 작업에서 쓴다. 지식이 거의 필요 없는 경우다.",
      "",
      "현장에서 반복적으로 나온 교훈:",
      "1. 평가(eval) 없이 튜닝하지 마라. 무엇이 나아졌는지 측정할 수 없으면 개선이 아니라 도박이다.",
      "2. 검색 품질이 RAG 품질의 상한이다. 리트리버를 고치는 게 프롬프트를 만지는 것보다 효과적이다.",
      "3. 파인튜닝은 마지막 수단이다. 데이터셋 유지보수 부담이 계속 따라온다.",
    ].join("\n"),
  },
  {
    url: "https://example.com/docs/evaluation-methods",
    title: "LLM 시스템 평가 방법론",
    topic: "general",
    content: [
      "RAG든 파인튜닝이든, 개선을 주장하려면 측정이 먼저다.",
      "",
      "RAG 평가는 두 층으로 나눈다.",
      "- 검색 평가: recall@k(정답 문서가 상위 k에 들어왔는가), MRR.",
      "  검색이 정답 문서를 못 가져오면 생성이 아무리 좋아도 답은 틀린다.",
      "- 생성 평가: faithfulness(답이 가져온 문서에 근거하는가), answer relevance.",
      "  faithfulness가 낮으면 모델이 문서를 무시하고 지어내고 있다는 뜻이다.",
      "",
      "파인튜닝 평가: 홀드아웃 테스트셋에서의 정확도, 형식 준수율.",
      "학습 데이터가 테스트셋에 새어 들어가는 오염(contamination)을 반드시 확인해야 한다.",
      "",
      "LLM-as-judge: 모델에게 채점을 시키는 방법. 빠르고 싸지만 편향이 있다.",
      "judge 모델은 긴 답변과 자기 자신이 만든 답변을 선호하는 경향이 알려져 있다.",
      "최소한 수십 개는 사람이 직접 채점해 judge와 일치하는지 검증하고 써야 한다.",
    ].join("\n"),
  },
];

/**
 * Step 12 — 종합 프로젝트: 딥 리서치 에이전트
 * 검색 도구 — 목(mock) 버전과 Tavily 버전.
 *
 * 실행: 이 파일은 직접 실행하지 않고 agent.ts 에서 import 합니다.
 *      목 검색만 단독 확인하려면: npx tsx docs/reference/deepagent/step-12-final-project/tools.ts
 */
import "dotenv/config";
import { tool } from "langchain";
import * as z from "zod";
import { MOCK_CORPUS, type CorpusDoc } from "./mock-corpus.js";

/* ===== [12-2] 검색 결과 포맷 — 두 도구가 같은 모양으로 돌려준다 ===== */

/**
 * 검색 결과 한 건. 목이든 Tavily든 이 모양으로 정규화해서 돌려줍니다.
 * 도구가 돌려주는 "문자열"의 형식을 고정해야 서브에이전트 프롬프트가 안정적으로 동작합니다.
 */
export interface SearchHit {
  url: string;
  title: string;
  content: string;
}

/**
 * 검색 결과를 모델이 읽을 문자열로 만듭니다.
 *
 * URL 을 결과마다 눈에 띄게 박아 넣는 것이 핵심입니다. 모델은 프롬프트에서 본 것만
 * 인용할 수 있습니다 — 결과에 URL 이 없으면 인용을 아무리 시켜도 지어냅니다.
 */
export function formatHits(query: string, hits: SearchHit[]): string {
  if (hits.length === 0) {
    // 빈 결과일 때 빈 문자열을 돌려주면 모델이 "도구가 고장났나?"를 판단하지 못하고
    // 같은 질의를 반복합니다. 그래서 "없다"는 사실을 문장으로 말해 줍니다.
    return `'${query}' 에 대한 검색 결과가 없습니다. 다른 키워드로 다시 시도하세요.`;
  }
  const body = hits
    .map(
      (h, i) =>
        `## [결과 ${i + 1}] ${h.title}\n**URL:** ${h.url}\n\n${h.content}\n\n---`,
    )
    .join("\n");
  return `'${query}' 에 대해 ${hits.length}건을 찾았습니다:\n\n${body}`;
}

/* ===== [12-2] 목 검색 도구 — API 키 없이 동작 ===== */

/** 한국어/영어를 대충 토큰으로 쪼갭니다. 목 검색용이라 정교할 필요는 없습니다. */
function tokenize(s: string): string[] {
  return s
    .toLowerCase()
    .split(/[^a-z0-9가-힣]+/)
    .filter((t) => t.length > 1);
}

/**
 * 아주 단순한 키워드 점수. 질의 토큰이 제목에 있으면 3점, 본문에 있으면 1점.
 * 임베딩 검색이 아니라 **결정적(deterministic)** 이라, 실습에서 매번 같은 결과가 나옵니다.
 */
function scoreDoc(queryTokens: string[], doc: CorpusDoc): number {
  const title = doc.title.toLowerCase();
  const content = doc.content.toLowerCase();
  let score = 0;
  for (const t of queryTokens) {
    if (title.includes(t)) score += 3;
    if (content.includes(t)) score += 1;
  }
  return score;
}

/**
 * 목 검색 도구.
 *
 * 외부 네트워크를 전혀 타지 않고 mock-corpus.ts 의 문서를 키워드로 검색합니다.
 * API 키가 없어도, 비행기 안에서도, 요금 걱정 없이 이 코스를 끝까지 실습할 수 있습니다.
 *
 * 이름(`web_search`)과 스키마를 Tavily 버전과 **완전히 동일하게** 맞춘 것이 중요합니다.
 * 그래야 프롬프트를 한 글자도 안 고치고 목 ↔ 실제를 갈아끼울 수 있습니다.
 */
export const mockSearch = tool(
  async ({
    query,
    maxResults = 3,
    topic = "general",
  }: {
    query: string;
    maxResults?: number;
    topic?: "general" | "news" | "finance";
  }) => {
    const tokens = tokenize(query);
    const pool =
      // topic 이 general 이면 전체를 뒤지고, 아니면 해당 topic 만 봅니다.
      topic === "general" ? MOCK_CORPUS : MOCK_CORPUS.filter((d) => d.topic === topic);

    const hits = pool
      .map((doc) => ({ doc, score: scoreDoc(tokens, doc) }))
      .filter((x) => x.score > 0)
      .sort((a, b) => b.score - a.score)
      .slice(0, maxResults)
      .map(({ doc }) => ({ url: doc.url, title: doc.title, content: doc.content }));

    return formatHits(query, hits);
  },
  {
    name: "web_search",
    // 설명이 곧 프롬프트입니다. "언제 부르는가"를 여기에 적어야 모델이 제때 부릅니다.
    description:
      "웹에서 주제에 대한 정보를 검색합니다. 관련 문서의 제목, URL, 본문을 돌려줍니다. " +
      "사실 확인이 필요한 모든 주장에 대해 호출하세요.",
    schema: z.object({
      query: z.string().describe("검색어. 구체적이고 서술적으로 작성하세요."),
      maxResults: z
        .number()
        .optional()
        .describe("돌려받을 최대 결과 수 (기본 3)"),
      topic: z
        .enum(["general", "news", "finance"])
        .optional()
        .describe("주제 필터. 'general'(기본) / 'news'(시사) / 'finance'(금융)"),
    }),
  },
);

/* ===== [12-2] Tavily 검색 도구 — 진짜 웹 ===== */

/**
 * URL 하나의 본문을 가져옵니다. Tavily 가 돌려주는 것은 URL 목록과 짧은 스니펫이라,
 * 깊은 조사를 하려면 본문을 직접 받아와야 합니다.
 *
 * timeout 이 없으면 응답 없는 서버 하나가 에이전트 전체를 멈춥니다. AbortController 필수.
 */
async function fetchWebpageContent(url: string, timeoutMs = 10_000): Promise<string> {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), timeoutMs);
  try {
    const response = await fetch(url, {
      headers: {
        "User-Agent":
          "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
      },
      signal: controller.signal,
    });
    if (!response.ok) {
      return `(${url} 을 가져오지 못했습니다: HTTP ${response.status})`;
    }
    const text = await response.text();
    // 본문을 통째로 넣으면 HTML 태그까지 토큰을 잡아먹습니다. 앞부분만 자릅니다.
    return text.slice(0, 8_000);
  } catch (e) {
    // 실패를 throw 하지 않고 문자열로 돌려주는 게 포인트입니다.
    // 도구가 throw 하면 에이전트 루프가 통째로 죽습니다. 문자열이면 모델이 읽고 대처합니다.
    return `(${url} 을 가져오지 못했습니다: ${String(e)})`;
  } finally {
    clearTimeout(timer);
  }
}

/**
 * Tavily 검색 도구. TAVILY_API_KEY 가 필요합니다(무료 티어 있음).
 * 스키마와 이름은 mockSearch 와 동일합니다.
 */
export const tavilySearch = tool(
  async ({
    query,
    maxResults = 3,
    topic = "general",
  }: {
    query: string;
    maxResults?: number;
    topic?: "general" | "news" | "finance";
  }) => {
    const apiKey = process.env.TAVILY_API_KEY;
    if (!apiKey) {
      return "TAVILY_API_KEY 가 설정되지 않아 검색할 수 없습니다.";
    }
    try {
      const response = await fetch("https://api.tavily.com/search", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${apiKey}`,
        },
        body: JSON.stringify({ query, max_results: maxResults, topic }),
      });
      if (!response.ok) {
        return `검색 실패: Tavily HTTP ${response.status}`;
      }
      const data = (await response.json()) as {
        results?: Array<{ url: string; title: string }>;
      };
      const results = data.results ?? [];

      // 본문 fetch 는 서로 독립이므로 병렬로 처리합니다. 순차로 하면 결과 수만큼 느려집니다.
      const hits: SearchHit[] = await Promise.all(
        results.map(async (r) => ({
          url: r.url,
          title: r.title,
          content: await fetchWebpageContent(r.url),
        })),
      );
      return formatHits(query, hits);
    } catch (e) {
      return `검색 실패: ${String(e)}`;
    }
  },
  {
    name: "web_search",
    description:
      "웹에서 주제에 대한 정보를 검색합니다. 관련 문서의 제목, URL, 본문을 돌려줍니다. " +
      "사실 확인이 필요한 모든 주장에 대해 호출하세요.",
    schema: z.object({
      query: z.string().describe("검색어. 구체적이고 서술적으로 작성하세요."),
      maxResults: z
        .number()
        .optional()
        .describe("돌려받을 최대 결과 수 (기본 3)"),
      topic: z
        .enum(["general", "news", "finance"])
        .optional()
        .describe("주제 필터. 'general'(기본) / 'news'(시사) / 'finance'(금융)"),
    }),
  },
);

/* ===== [12-2] 자동 선택 ===== */

/**
 * TAVILY_API_KEY 가 있으면 진짜 검색을, 없으면 목 검색을 돌려줍니다.
 * 두 도구의 이름·스키마가 같기 때문에 나머지 코드는 어느 쪽인지 알 필요가 없습니다.
 */
export function createSearchTool() {
  return process.env.TAVILY_API_KEY ? tavilySearch : mockSearch;
}

/** 지금 어떤 검색을 쓰는지 사람이 읽을 이름. CLI 배너에 씁니다. */
export function searchToolLabel(): string {
  return process.env.TAVILY_API_KEY ? "Tavily (실제 웹)" : "Mock (오프라인 코퍼스)";
}

/* ===== 단독 실행: 목 검색 동작 확인 ===== */

// 이 파일을 직접 실행했을 때만 아래가 돕니다. import 될 때는 실행되지 않습니다.
if (import.meta.url === `file://${process.argv[1]}`) {
  const out = await mockSearch.invoke({
    query: "RAG와 파인튜닝의 비용 차이",
    maxResults: 2,
  });
  console.log(out);
}

/**
 * Step 12 — 종합 프로젝트: 딥 리서치 에이전트
 * 시스템 프롬프트 전문.
 *
 * 프롬프트를 코드에서 분리한 이유: 프롬프트는 이 프로젝트에서 가장 자주 고치는 파일입니다.
 * 에이전트 배선(agent.ts)과 섞여 있으면 diff 를 읽을 수 없게 됩니다.
 */

/** 오늘 날짜. 모델은 오늘이 며칠인지 모릅니다 — 안 알려주면 학습 시점 날짜로 추측합니다. */
export const TODAY = new Date().toISOString().split("T")[0];

/* ===== [12-6] 부모(오케스트레이터) 프롬프트 ===== */

/**
 * 부모 에이전트 프롬프트.
 *
 * 부모가 하는 일: 계획 → 위임 → 종합. **부모는 직접 검색하지 않습니다.**
 * 부모가 검색하면 검색 결과 원문이 부모 컨텍스트에 쌓여, 서브에이전트를 쓰는 의미가 사라집니다.
 */
export const ORCHESTRATOR_PROMPT = `당신은 딥 리서치 오케스트레이터입니다. 오늘 날짜는 ${TODAY} 입니다.

당신의 역할은 **직접 조사하는 것이 아니라, 조사를 지휘하고 결과를 종합하는 것**입니다.
당신에게는 web_search 도구가 없습니다. 모든 조사는 task() 로 서브에이전트에게 위임하세요.

# 작업 절차

아래 순서를 반드시 지키세요.

1. **질문 저장**: write_file 로 사용자의 원래 질문을 \`/question.txt\` 에 그대로 저장합니다.
   나중에 "내가 무슨 질문에 답하고 있었지?"를 확인하는 기준점이 됩니다.
2. **계획**: write_todos 로 리서치 단계를 3~6개의 할 일로 쪼갭니다.
   할 일은 "무엇을 알아낼 것인가"로 쓰세요. "검색한다" 같은 행위가 아니라 "X의 비용 구조를 파악한다" 처럼.
3. **조사 위임**: task() 로 research-subagent 를 호출합니다.
   - 서브에이전트에게는 **한 번에 하나의 구체적인 주제**만 줍니다.
   - 서브에이전트는 당신의 대화 내용을 볼 수 없습니다. 배경을 포함해 **자기완결적으로** 지시하세요.
     나쁜 예: "그것에 대해 더 조사해줘"
     좋은 예: "RAG(검색 증강 생성)의 추론 비용 구조를 조사해라. 특히 토큰 오버헤드와 절감 기법을 다뤄라."
   - 조사 결과는 write_file 로 \`/findings/<주제-슬러그>.md\` 에 저장하라고 지시하세요.
4. **비평**: 조사가 끝나면 task() 로 critique-subagent 를 호출해 \`/findings/\` 를 검토시킵니다.
   비평이 지적한 구멍은 다시 research-subagent 에게 보내 메웁니다.
5. **보고서 작성**: 모든 findings 를 read_file 로 읽고 종합해 \`/report.md\` 에 씁니다.
6. **검증**: \`/question.txt\` 를 다시 읽고, 보고서가 질문의 모든 측면에 답했는지 확인합니다.

# 위임 전략

- **기본은 서브에이전트 1개**입니다. 단순 질문을 여러 개로 쪼개면 토큰만 낭비됩니다.
  "X가 무엇인가" → 1개.
- **명시적 비교나 독립된 축이 있을 때만 병렬로** 나눕니다.
  "A와 B를 비교하라" → A 담당 1개 + B 담당 1개.
  "유럽/아시아/북미의 현황" → 지역별 3개.
- 한 번에 최대 3개까지만 병렬로 띄우세요. 병렬 실행은 한 응답에서 task() 를 여러 번 호출하면 됩니다.
- 위임 라운드는 최대 3회입니다. 그 안에 충분한 근거를 못 모았으면, 모은 것으로 답하고
  보고서에 "무엇을 확인하지 못했는지" 한계를 명시하세요.

# 보고서 작성 규칙

\`/report.md\` 는 다음을 지킵니다.

- 구조: 비교 질문이면 (도입 → A 개요 → B 개요 → 상세 비교 → 결론).
  개요 질문이면 (개요 → 핵심 개념들 → 결론). 목록 질문이면 도입 없이 바로 항목 나열.
- 문체: **평서문, 문단 중심**으로 씁니다. 불릿만 나열하지 마세요.
- 자기 지칭 금지: "제가 조사한 결과", "찾아보니" 같은 표현을 쓰지 마세요.
  보고서는 리서처의 일기가 아니라 **문서**입니다.
- 섹션 제목은 \`##\`, 하위는 \`###\` 를 씁니다.

# 인용 규칙 (엄격)

- 모든 사실 주장 뒤에 \`[1]\`, \`[2]\` 형식으로 출처 번호를 답니다.
- **번호는 URL 단위로 전역에서 유일**해야 합니다. 서로 다른 findings 파일이 같은 URL 을 쓰면 같은 번호를 씁니다.
- 보고서 맨 끝에 \`### 출처\` 섹션을 만들고, 번호 순서대로 빠짐없이(1,2,3...) 나열합니다.
- 형식: \`[1] 문서 제목: URL\` — 한 줄에 하나씩.
- **findings 에 없는 URL 을 지어내지 마세요.** 출처가 없는 주장은 아예 쓰지 마세요.

# 절대 규칙

- 당신은 web_search 를 갖고 있지 않습니다. 조사는 반드시 위임하세요.
- findings 에 근거가 없는 내용을 보고서에 쓰지 마세요. 모르면 "확인되지 않음"이라고 쓰세요.
- 최종 보고서는 반드시 \`/report.md\` 에 write_file 로 저장하세요. 채팅 답변으로만 끝내지 마세요.`;

/* ===== [12-3] 조사 서브에이전트 프롬프트 ===== */

/**
 * 조사 담당. 싼 모델로 돌립니다.
 *
 * 여기서 가장 중요한 건 **검색 예산(budget)** 입니다. 상한이 없으면 모델은
 * "조금만 더 찾으면 완벽해질 것 같은" 상태에 빠져 검색을 반복합니다. 비용이 여기서 터집니다.
 */
export const RESEARCHER_PROMPT = `당신은 리서치 어시스턴트입니다. 오늘 날짜는 ${TODAY} 입니다.

web_search 도구로 주어진 주제를 조사하고, 결과를 정리해 돌려주는 것이 당신의 일입니다.

# 조사 방법

시간이 한정된 사람 연구자처럼 행동하세요.

1. **질문을 정확히 읽습니다.** 무엇을 알아내야 하는가?
2. **넓은 질의로 시작합니다.** 처음부터 좁게 파고들면 큰 그림을 놓칩니다.
3. **검색할 때마다 멈춰서 평가합니다.** 지금 답할 수 있는가? 무엇이 빠졌는가?
4. **빈 곳을 좁은 질의로 메웁니다.**
5. **자신 있게 답할 수 있으면 멈춥니다.** 완벽을 좇지 마세요.

# 검색 예산 (반드시 지킬 것)

- 단순한 주제: 검색 **2~3회**.
- 복잡한 주제: 검색 **최대 5회**.
- 5회를 넘기면 무조건 멈추고, 지금까지 찾은 것으로 답하세요.

# 즉시 멈춰야 하는 조건

- 질문에 충분히 답할 수 있게 되었을 때
- 관련 출처를 3개 이상 확보했을 때
- **최근 2회 검색이 비슷한 내용만 돌려줄 때** (더 해도 안 나옵니다)

# 결과 저장

조사가 끝나면 write_file 로 \`/findings/<주제-슬러그>.md\` 에 저장하세요.
슬러그는 영문 소문자와 하이픈만 씁니다 (예: \`/findings/rag-cost.md\`).

파일 형식:

\`\`\`markdown
# <주제>

## 핵심 발견
(문단으로 서술. 각 주장 뒤에 [1], [2] 인용을 답니다.)

## 확인하지 못한 것
(검색으로 찾지 못한 것을 솔직히 적습니다. 없으면 "없음")

### 출처
[1] 문서 제목: URL
[2] 문서 제목: URL
\`\`\`

# 인용 규칙

- 모든 사실 주장에 \`[1]\` 형식의 번호를 답니다.
- **번호는 반드시 검색 결과에 실제로 나온 URL 에만 붙입니다.**
- URL 을 절대 지어내지 마세요. 검색 결과의 \`**URL:**\` 줄에 있는 것을 그대로 복사하세요.

# 부모에게 돌려줄 응답

파일을 저장한 뒤, 부모에게는 **요약**을 돌려주세요.
검색 결과 원문을 그대로 붙여넣지 마세요 — 부모의 컨텍스트가 터집니다.
돌려줄 내용: (1) 저장한 파일 경로, (2) 핵심 발견 3~5줄, (3) 확인하지 못한 것.`;

/* ===== [12-3] 비평 서브에이전트 프롬프트 ===== */

/**
 * 비평 담당.
 *
 * 비평가에게 web_search 를 주지 않은 것이 의도적입니다. 검색이 있으면 비평가가
 * 스스로 조사를 시작해 버립니다. 비평가의 일은 **조사가 아니라 심사**입니다.
 */
export const CRITIQUE_PROMPT = `당신은 리서치 결과를 심사하는 비평가입니다. 오늘 날짜는 ${TODAY} 입니다.

당신에게는 검색 도구가 없습니다. 이것은 의도된 것입니다.
당신의 일은 새로 조사하는 것이 아니라, **이미 조사된 것의 결함을 찾는 것**입니다.

# 절차

1. ls 로 \`/findings/\` 에 어떤 파일이 있는지 봅니다.
2. read_file 로 각 파일을 **전부** 읽습니다.
3. \`/question.txt\` 를 읽어 원래 질문이 무엇이었는지 확인합니다.
4. 아래 기준으로 심사합니다.

# 심사 기준

- **인용 누락**: 출처 번호 없이 단언한 사실 주장이 있는가?
- **출처 유령**: 본문에서 \`[3]\` 을 썼는데 출처 목록에 3번이 없는가? 반대로 목록에만 있고 본문에 안 쓰였는가?
- **질문 미달**: 원래 질문에서 아직 아무도 답하지 않은 측면이 있는가?
- **근거 빈약**: 출처 하나에만 의존하는 중요한 주장이 있는가?
- **모순**: findings 파일들끼리 서로 반대되는 말을 하는가?

# 출력 형식

반드시 아래 형식으로만 답하세요. 다른 말은 하지 마세요.

판정: PASS 또는 REVISE

PASS 는 위 기준에 걸리는 것이 하나도 없을 때만 줍니다. 어정쩡하면 REVISE 입니다.

REVISE 인 경우, 다음을 각 항목마다 적습니다.
- 문제: (무엇이 잘못되었는가)
- 위치: (어느 파일의 어느 부분인가)
- 조치: (부모가 재조사를 지시할 수 있도록, **구체적인 조사 주제 한 문장**으로 쓸 것)

칭찬하지 마세요. 잘된 점을 적지 마세요. 문제만 적으세요.`;

/**
 * Step 12 — 종합 프로젝트: 딥 리서치 에이전트
 * 서브에이전트 정의.
 */
import "dotenv/config";
import type { SubAgent } from "deepagents";
import { createSearchTool } from "./tools.js";
import { RESEARCHER_PROMPT, CRITIQUE_PROMPT } from "./prompts.js";

/* ===== [12-3] 모델 선택 — 역할마다 다른 모델 ===== */

/**
 * 부모(종합) 모델. 여러 findings 를 읽고 하나의 보고서로 엮는, 이 시스템에서 가장 어려운 일을 합니다.
 * 여기서 아끼면 보고서 품질이 무너집니다.
 */
export const ORCHESTRATOR_MODEL =
  process.env.ORCHESTRATOR_MODEL ?? "anthropic:claude-sonnet-4-6";

/**
 * 조사 모델. 검색 결과를 읽고 요약하는, 상대적으로 쉬운 일입니다.
 * 호출 횟수가 가장 많은 것도 여기라서, 싼 모델로 바꿨을 때 비용 절감 효과가 가장 큽니다.
 *
 * OpenAI 를 쓰려면: ORCHESTRATOR_MODEL=openai:gpt-5.5 RESEARCH_MODEL=openai:gpt-5.5-mini
 */
export const RESEARCH_MODEL =
  process.env.RESEARCH_MODEL ?? "anthropic:claude-haiku-4-5";

/** 비평 모델. 판정만 내리므로 싼 모델로 충분합니다. */
export const CRITIQUE_MODEL = process.env.CRITIQUE_MODEL ?? RESEARCH_MODEL;

/* ===== [12-3] 조사 서브에이전트 ===== */

/**
 * 조사 담당.
 *
 * `description` 은 부모가 "언제 이 서브에이전트를 부를지" 판단하는 **유일한 근거**입니다.
 * 부모는 systemPrompt 를 볼 수 없습니다. description 이 부실하면 부모가 안 부릅니다.
 */
export const researchSubagent: SubAgent = {
  name: "research-subagent",
  description:
    "웹 검색으로 하나의 구체적인 주제를 깊이 조사하고, 결과를 /findings/ 에 저장한 뒤 요약을 돌려줍니다. " +
    "한 번에 하나의 주제만 주세요. 배경 설명을 포함해 자기완결적으로 지시해야 합니다.",
  systemPrompt: RESEARCHER_PROMPT,
  tools: [createSearchTool()],
  model: RESEARCH_MODEL,
};

/* ===== [12-3] 비평 서브에이전트 ===== */

/**
 * 비평 담당.
 *
 * `tools` 를 **빈 배열로 두지 않은** 것에 주의하세요. 빈 배열이면 파일도 못 읽습니다.
 * 여기서는 tools 를 아예 지정하지 않아, 파일시스템 도구(read_file/ls)는 그대로 상속받고
 * web_search 는 부모가 갖고 있지 않으므로 자연히 없습니다.
 */
export const critiqueSubagent: SubAgent = {
  name: "critique-subagent",
  description:
    "/findings/ 의 조사 결과를 심사해 PASS 또는 REVISE 를 판정합니다. 검색은 하지 않습니다. " +
    "인용 누락, 출처 유령, 질문 미달, 근거 빈약, 모순을 찾아냅니다. 조사가 끝난 뒤 호출하세요.",
  systemPrompt: CRITIQUE_PROMPT,
  model: CRITIQUE_MODEL,
};

export const allSubagents: SubAgent[] = [researchSubagent, critiqueSubagent];

/**
 * Step 12 — 종합 프로젝트: 딥 리서치 에이전트
 * 에이전트 배선.
 */
import "dotenv/config";
import { createDeepAgent } from "deepagents";
import { MemorySaver } from "@langchain/langgraph";
import { ORCHESTRATOR_PROMPT } from "./prompts.js";
import { allSubagents, ORCHESTRATOR_MODEL } from "./subagents.js";

/* ===== [12-7] HITL 옵션 ===== */

export interface BuildOptions {
  /**
   * true 면 /report.md 를 쓰기 직전에 멈춰 사람의 승인을 받습니다.
   * checkpointer 가 반드시 함께 있어야 합니다 — 없으면 멈춘 지점을 저장할 곳이 없습니다.
   */
  requireApproval?: boolean;
}

/* ===== [12-1] 에이전트 조립 ===== */

/**
 * 딥 리서치 에이전트를 만듭니다.
 *
 * 설계 요약:
 * - 부모는 web_search 를 **갖지 않습니다**. tools 가 비어 있는 게 실수가 아니라 설계입니다.
 *   부모가 검색하면 결과 원문이 부모 컨텍스트에 쌓여 서브에이전트의 존재 이유가 사라집니다.
 * - 검색 도구는 research-subagent 만 갖습니다 (subagents.ts 참고).
 * - 파일시스템/write_todos/task 는 deepagents 가 기본으로 넣어 줍니다.
 * - 백엔드를 지정하지 않았으므로 기본값인 StateBackend 를 씁니다.
 *   파일이 실제 디스크가 아니라 **에이전트 상태(state) 안**에만 존재합니다.
 */
export function buildResearchAgent(options: BuildOptions = {}) {
  const { requireApproval = false } = options;

  // 체크포인터는 HITL 에 필수입니다. interrupt 는 "여기서 멈췄다"를 어딘가에 적어야 재개할 수 있는데,
  // 그 어딘가가 체크포인터입니다. MemorySaver 는 프로세스 메모리라 재시작하면 사라집니다(문제 5 참고).
  const checkpointer = requireApproval ? new MemorySaver() : undefined;

  return createDeepAgent({
    model: ORCHESTRATOR_MODEL,
    systemPrompt: ORCHESTRATOR_PROMPT,
    tools: [], // 의도적으로 비움 — 위 주석 참고
    subagents: allSubagents,
    checkpointer,
    // write_file 중에서도 /report.md 를 쓸 때만 멈춥니다.
    // when 없이 write_file 전체에 걸면 findings 저장마다 승인 창이 떠서 실습이 불가능해집니다.
    interruptOn: requireApproval
      ? {
          write_file: {
            allowedDecisions: ["approve", "edit", "reject"],
            when: (request) =>
              String(request.toolCall.args.file_path ?? "") === "/report.md",
          },
        }
      : undefined,
  });
}

/* ===== [12-4] 상태에서 파일 꺼내기 ===== */

/**
 * StateBackend 가 상태에 넣어 둔 파일 내용을 문자열로 꺼냅니다.
 *
 * ⚠️ 파일 content 는 두 가지 형식이 존재합니다.
 *   - v1: string[] (줄 배열)
 *   - v2: string | Uint8Array (텍스트 또는 바이너리)
 * 어느 쪽이 올지 가정하고 `.join("\n")` 만 부르면 v2 에서 조용히 깨집니다
 * (문자열에 .join 은 없으므로 TypeError, 혹은 타입 단언을 썼다면 이상한 값).
 * 그래서 두 형식을 모두 받아냅니다.
 */
export function readStateFile(
  files: Record<string, unknown> | undefined,
  path: string,
): string | undefined {
  const entry = files?.[path] as { content?: unknown } | undefined;
  if (!entry) return undefined;

  const content = entry.content;
  if (typeof content === "string") return content; // v2 텍스트
  if (Array.isArray(content)) return content.join("\n"); // v1 줄 배열
  if (content instanceof Uint8Array) {
    return new TextDecoder().decode(content); // v2 바이너리
  }
  return undefined;
}

/** 상태에 들어 있는 파일 경로를 정렬해 돌려줍니다. CLI 에서 결과 요약에 씁니다. */
export function listStateFiles(files: Record<string, unknown> | undefined): string[] {
  return Object.keys(files ?? {}).sort();
}

/**
 * Step 12 — 종합 프로젝트: 딥 리서치 에이전트
 * CLI 진입점.
 *
 * 실행:
 *   npx tsx docs/reference/deepagent/step-12-final-project/cli.ts "질문"
 *   npx tsx docs/reference/deepagent/step-12-final-project/cli.ts --approve "질문"
 *   npx tsx docs/reference/deepagent/step-12-final-project/cli.ts --out ./report.md "질문"
 */
import "dotenv/config";
import * as readline from "node:readline/promises";
import { stdin, stdout } from "node:process";
import { writeFile } from "node:fs/promises";
import { Command } from "@langchain/langgraph";
import { buildResearchAgent, readStateFile, listStateFiles } from "./agent.js";
import { searchToolLabel } from "./tools.js";

/* ===== [12-8] 인자 파싱 ===== */

const argv = process.argv.slice(2);

const requireApproval = argv.includes("--approve");
const outIndex = argv.indexOf("--out");
const outPath = outIndex >= 0 ? argv[outIndex + 1] : undefined;

// 플래그와 그 값을 걷어내고 남은 것이 질문입니다.
const question =
  argv
    .filter((a, i) => {
      if (a === "--approve") return false;
      if (a === "--out") return false;
      if (outIndex >= 0 && i === outIndex + 1) return false;
      return true;
    })
    .join(" ")
    .trim() || "RAG와 파인튜닝의 주요 차이점은 무엇인가?";

if (!process.env.ANTHROPIC_API_KEY) {
  console.error(
    "ANTHROPIC_API_KEY 가 없습니다. .env 에 넣거나 환경변수로 주세요.\n" +
      "(검색은 키 없이도 목으로 동작하지만, 모델 호출은 키가 필요합니다.)",
  );
  process.exit(1);
}

console.log("=".repeat(72));
console.log("딥 리서치 에이전트");
console.log("=".repeat(72));
console.log(`질문   : ${question}`);
console.log(`검색   : ${searchToolLabel()}`);
console.log(`승인   : ${requireApproval ? "켜짐 (/report.md 쓰기 전 확인)" : "꺼짐"}`);
console.log("=".repeat(72));
console.log();

/* ===== [12-8] 실행 ===== */

const agent = buildResearchAgent({ requireApproval });

// thread_id 는 체크포인터가 대화를 식별하는 키입니다.
// HITL 로 멈췄다가 재개할 때 **같은 thread_id 로 다시 호출**해야 이어집니다.
const config = { configurable: { thread_id: crypto.randomUUID() } };

const input = { messages: [{ role: "user" as const, content: question }] };

// recursionLimit 기본값(25)은 딥 리서치에 턱없이 부족합니다.
// 계획 → 위임 → 비평 → 종합만 해도 스텝이 수십 개를 넘어갑니다.
// 넘으면 GraphRecursionError 가 납니다 — 무한루프가 아니라 그냥 일이 많은 겁니다.
let result = await agent.invoke(input, { ...config, recursionLimit: 100 });

/* ===== [12-7] HITL — 최종 보고서 승인 ===== */

// interrupt 로 멈추면 결과에 __interrupt__ 가 들어 있습니다.
// 승인/거절할 때까지 이 루프를 돕니다 — 한 번 거절하면 모델이 다시 쓰려 하므로 또 멈춥니다.
while (requireApproval && "__interrupt__" in result) {
  const interrupts = (result as Record<string, unknown>)["__interrupt__"] as Array<{
    value?: unknown;
  }>;

  const payload = interrupts?.[0]?.value as
    | { actionRequests?: Array<{ name: string; args: Record<string, unknown> }> }
    | undefined;
  const action = payload?.actionRequests?.[0];

  console.log("\n" + "-".repeat(72));
  console.log("[승인 요청] 에이전트가 최종 보고서를 쓰려 합니다.");
  console.log("-".repeat(72));

  const draft = String(action?.args?.content ?? "");
  // 보고서 전문을 다 보여주면 터미널이 넘칩니다. 앞부분만 보여주고 길이를 알려줍니다.
  console.log(draft.slice(0, 1_500));
  if (draft.length > 1_500) {
    console.log(`\n... (총 ${draft.length}자 중 앞 1500자만 표시)`);
  }
  console.log("-".repeat(72));

  const rl = readline.createInterface({ input: stdin, output: stdout });
  const answer = (await rl.question("승인하시겠습니까? [y=승인 / n=거절] : "))
    .trim()
    .toLowerCase();
  rl.close();

  // 재개는 Command({ resume: ... }) 로 합니다.
  // resume 페이로드는 { decisions: [...] } 모양이어야 합니다 — 배열이 아니라 객체입니다.
  if (answer === "y") {
    result = await agent.invoke(
      new Command({ resume: { decisions: [{ type: "approve" }] } }),
      { ...config, recursionLimit: 100 },
    );
  } else {
    const rl2 = readline.createInterface({ input: stdin, output: stdout });
    const reason =
      (await rl2.question("거절 사유 (모델에게 전달됩니다) : ")).trim() ||
      "보고서가 요구사항을 만족하지 않습니다. 다시 작성하세요.";
    rl2.close();

    result = await agent.invoke(
      new Command({ resume: { decisions: [{ type: "reject", message: reason }] } }),
      { ...config, recursionLimit: 100 },
    );
  }
}

/* ===== [12-8] 결과 출력 ===== */

const files = (result as { files?: Record<string, unknown> }).files;

console.log("\n" + "=".repeat(72));
console.log("생성된 파일");
console.log("=".repeat(72));
for (const path of listStateFiles(files)) {
  const body = readStateFile(files, path) ?? "";
  console.log(`  ${path}  (${body.length}자)`);
}

const report = readStateFile(files, "/report.md");

console.log("\n" + "=".repeat(72));
console.log("최종 보고서 (/report.md)");
console.log("=".repeat(72));
console.log(report ?? "(보고서가 생성되지 않았습니다)");

if (outPath && report) {
  await writeFile(outPath, report, "utf-8");
  console.log(`\n→ ${outPath} 에 저장했습니다.`);
}

/* ===== [12-9] 사용량 ===== */

// usage_metadata 는 AIMessage 에만 있습니다. 서브에이전트의 토큰은 부모 메시지에 안 잡힙니다
// (그게 컨텍스트 격리의 요점입니다). 따라서 이 숫자는 **부모만의 사용량**입니다.
const messages = result.messages ?? [];
let inputTokens = 0;
let outputTokens = 0;
for (const m of messages) {
  // usage_metadata 는 AIMessage 에만 있으므로 BaseMessage 타입에는 없습니다.
  // unknown 을 거쳐 좁히는 것이 정직한 방법입니다 — 바로 단언하면 tsc 가 막습니다(TS2352).
  const usage = (m as unknown as { usage_metadata?: unknown }).usage_metadata as
    | { input_tokens?: number; output_tokens?: number }
    | undefined;
  if (usage) {
    inputTokens += usage.input_tokens ?? 0;
    outputTokens += usage.output_tokens ?? 0;
  }
}

console.log("\n" + "=".repeat(72));
console.log("사용량 (부모 에이전트만 — 서브에이전트 토큰은 포함되지 않습니다)");
console.log("=".repeat(72));
console.log(`  입력 토큰 : ${inputTokens.toLocaleString()}`);
console.log(`  출력 토큰 : ${outputTokens.toLocaleString()}`);
console.log(`  메시지 수 : ${messages.length}`);