#Step 08 — 미들웨어 조합

return createAgent({
  model,
  systemPrompt: assemblePromptParts(promptParts),  // ← Step 07 의 prefix→base→suffix
  stateSchema,
  tools: effectiveTools,
  middleware,                                       // ← 위 스택
  responseFormat,
  contextSchema,
  checkpointer,
  store,
  name,
  streamTransformers,
}).withConfig({
  recursionLimit: 10000,
  metadata: { ls_integration: "deepagents", lc_agent_name: name },
});

import { createMiddleware } from "langchain";

function makeInspector(label: string) {
  let done = false;
  return createMiddleware({
    name: "InspectorMiddleware",
    wrapModelCall: async (request, handler) => {
      if (!done) {
        done = true;
        const toolNames = request.tools.map((t: any) => t.name).sort();
        console.log(`[${label}] 도구(${toolNames.length}): ${toolNames.join(", ")}`);
        console.log(`[${label}] 프롬프트 길이: ${(request.systemMessage.text ?? "").length}`);
      }
      return handler(request);
    },
  });
}

const agent = await createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  tools: [getWeather],                        // ← 내가 준 건 이거 하나
  systemPrompt: "당신은 날씨 봇입니다.",
  middleware: [makeInspector("createDeepAgent 기본")],
});

await agent.invoke({ messages: [{ role: "user", content: "안녕" }] });

import { createAgent, todoListMiddleware, anthropicPromptCachingMiddleware } from "langchain";
import {
  createFilesystemMiddleware,
  createSubAgentMiddleware,
  createSummarizationMiddleware,
  createPatchToolCallsMiddleware,
  StateBackend,
} from "deepagents";

// createDeepAgent 의 backend 기본값이 정확히 이것입니다.
const backend = (config: { state: unknown; store?: any }) => new StateBackend(config);
const tools = [getWeather];

// (A) createDeepAgent
const deep = await createDeepAgent({
  model: MODEL,
  tools,
  systemPrompt: "당신은 날씨 봇입니다.",
  middleware: [makeInspector("A. createDeepAgent", deepSink)],
});
await deep.invoke({ messages: [{ role: "user", content: "안녕" }] });

// (B) createAgent + 미들웨어 스택 직접 조립
const manual = createAgent({
  model: MODEL,
  tools,
  systemPrompt: "당신은 날씨 봇입니다.",   // ← 여기선 '교체'다. createDeepAgent 와 의미가 다르다 (Step 07)
  middleware: [
    todoListMiddleware(),
    createFilesystemMiddleware({ backend }),
    createSubAgentMiddleware({
      defaultModel: MODEL,
      defaultTools: tools,
      subagents: [],
      generalPurposeAgent: true,
    }),
    createSummarizationMiddleware({ backend }),
    createPatchToolCallsMiddleware(),
    anthropicPromptCachingMiddleware({
      unsupportedModelBehavior: "ignore",
      minMessagesToCache: 1,
    }),
    makeInspector("B. 직접 조립", manualSink),
  ],
}).withConfig({ recursionLimit: 10000 });

await manual.invoke({ messages: [{ role: "user", content: "안녕" }] });

// ✅ export 됨
import { TASK_SYSTEM_PROMPT, DEFAULT_SUBAGENT_PROMPT, DEFAULT_GENERAL_PURPOSE_DESCRIPTION,
         GENERAL_PURPOSE_SUBAGENT, REQUIRED_MIDDLEWARE_NAMES } from "deepagents";

// ❌ export 안 됨 — 직접 써야 함
// BASE_AGENT_PROMPT

const fsOnly = createAgent({
  model: MODEL,
  systemPrompt: "당신은 메모 도우미입니다. 요청받은 내용을 /notes/ 아래 파일로 정리하세요.",
  middleware: [createFilesystemMiddleware({ backend })],
});

const r = await fsOnly.invoke({
  messages: [{ role: "user", content: "오늘 회의 결론 '배포는 금요일'을 메모해줘." }],
});
console.log("생성된 파일:", Object.keys((r as any).files ?? {}));

const planOnly = createAgent({
  model: MODEL,
  tools: [getWeather],
  systemPrompt: "당신은 여행 플래너입니다.",
  middleware: [todoListMiddleware()],
});

const r = await planOnly.invoke({
  messages: [{ role: "user", content: "서울, 부산, 제주 날씨를 확인하고 여행지를 추천하는 계획을 세워줘." }],
});
console.log("todos:", (r as any).todos);

const readOnly = createAgent({
  model: MODEL,
  systemPrompt: "당신은 코드 탐색기입니다. 파일을 수정하지 마세요.",
  middleware: [
    createFilesystemMiddleware({ backend, tools: ["read_file", "ls", "glob", "grep"] }),
  ],
});

const logging = createMiddleware({
  name: "LogToolCallsMiddleware",       // ← 기본 스택에 없는 이름
  wrapToolCall: async (request, handler) => {
    console.log(`[로그] ${request.toolCall.name}`);
    return handler(request);
  },
});

const agent = await createDeepAgent({
  model: MODEL,
  tools: [getWeather],
  systemPrompt: "당신은 날씨 봇입니다.",
  middleware: [logging],
});

import { summarizationMiddleware } from "langchain";   // ← langchain 것

const agent = await createDeepAgent({
  model: MODEL,
  tools: [getWeather],
  systemPrompt: "당신은 날씨 봇입니다.",
  middleware: [
    summarizationMiddleware({ model: MODEL, maxTokensBeforeSummary: 1000 }),
  ],
});

const marker = (n: string) =>
  createMiddleware({
    name: `Marker${n}Middleware`,
    wrapModelCall: async (request, handler) => {
      console.log(`  들어감: ${n}`);
      const r = await handler({
        ...request,
        systemMessage: request.systemMessage.concat(`\n[${n}]`),
      });
      console.log(`  나옴:   ${n}`);
      return r;
    },
  });

const agent = createAgent({
  model: MODEL,
  systemPrompt: "짧게 답하세요.",
  middleware: [marker("첫째"), marker("둘째"), marker("셋째")],
});
await agent.invoke({ messages: [{ role: "user", content: "안녕" }] });

const wrong = createAgent({
  model: MODEL,
  middleware: [
    createFilesystemMiddleware({ backend }),      // ← 부모에게만 파일 도구가 생긴다
    createSubAgentMiddleware({
      defaultModel: MODEL,
      subagents: [
        {
          name: "note-taker",
          description: "받은 내용을 /notes.md 에 저장하는 서브에이전트",
          systemPrompt: "받은 내용을 /notes.md 에 write_file 로 저장하세요.",
        },
      ],
      generalPurposeAgent: false,
    }),
    // defaultMiddleware 가 없다!
  ],
  systemPrompt: "note-taker 서브에이전트에게 위임하세요.",
});

const right = createAgent({
  model: MODEL,
  middleware: [
    createFilesystemMiddleware({ backend }),
    createSubAgentMiddleware({
      defaultModel: MODEL,
      defaultMiddleware: [createFilesystemMiddleware({ backend })],   // ← 이 한 줄이 핵심
      subagents: [ /* 위와 동일 */ ],
      generalPurposeAgent: false,
    }),
  ],
  systemPrompt: "note-taker 서브에이전트에게 위임하세요.",
});

// deepagents 내부 (createSubagentDefaultMiddleware)
[
  todoListMiddleware(),
  createFilesystemMiddleware({ backend, permissions, tools }),
  createSummarizationMiddleware({ backend }),
  createPatchToolCallsMiddleware(),
  ...(서브에이전트가 skills 를 가지면 createSkillsMiddleware(...)),
]

// deepagents 내부 (createDeepAgent)
let cacheMiddleware = [];
if (anthropicModel) cacheMiddleware = [
  ...cacheMiddleware,
  anthropicPromptCachingMiddleware({ unsupportedModelBehavior: "ignore", minMessagesToCache: 1 }),
  createCacheBreakpointMiddleware(),
];
if (bedrockModel) cacheMiddleware = [
  ...cacheMiddleware,
  bedrockPromptCachingMiddleware({ unsupportedModelBehavior: "ignore" }),
];

const usageSpy = createMiddleware({
  name: "UsageSpyMiddleware",
  afterModel: async (state) => {
    const u = (state.messages.at(-1) as any)?.usage_metadata;
    if (u) {
      console.log(
        `  입력=${u.input_tokens} 출력=${u.output_tokens} ` +
          `캐시생성=${u.input_token_details?.cache_creation ?? 0} ` +
          `캐시읽기=${u.input_token_details?.cache_read ?? 0}`,
      );
    }
    return undefined;
  },
});

const agent = await createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  tools: [getWeather],
  systemPrompt: "당신은 날씨 봇입니다.",
  middleware: [usageSpy],
});

const r1 = await agent.invoke({ messages: [{ role: "user", content: "서울 날씨?" }] });
await agent.invoke({ messages: [...r1.messages, { role: "user", content: "부산은?" }] });

import { anthropicPromptCachingMiddleware, bedrockPromptCachingMiddleware } from "langchain";

middleware: [
  // ... 나머지 스택
  anthropicPromptCachingMiddleware({ unsupportedModelBehavior: "ignore", minMessagesToCache: 1 }),
]

import { TASK_SYSTEM_PROMPT } from "deepagents";

const backend = (config: { state: unknown; store?: any }) => new StateBackend(config);

// 서브에이전트용 스택을 변수로 빼서 명시 (8-6)
const subagentMiddleware = [
  createFilesystemMiddleware({ backend }),
  createPatchToolCallsMiddleware(),
];

const agent = createAgent({
  model: MODEL,
  tools: [search],
  systemPrompt: `당신은 언어 리서처입니다.

## 워크플로
1. 조사할 언어가 2개 이상이면 write_todos 로 계획을 세운다.
2. 각 언어는 researcher 서브에이전트에게 task 로 위임한다.
3. 결과를 /report.md 에 write_file 로 저장한다.

## 도구 사용 규칙
- search 가 "NOT_FOUND" 를 반환하면 "자료 없음" 으로 표기한다. 지어내지 않는다.
- 파일 경로는 항상 /로 시작한다.

## 중단 조건
- /report.md 를 쓴 뒤 즉시 종료한다.

${TASK_SYSTEM_PROMPT}`,          // ← 내장 task 지침 재사용. export 되어 있다.
  middleware: [
    todoListMiddleware(),
    createFilesystemMiddleware({ backend }),
    createSubAgentMiddleware({
      defaultModel: MODEL,
      defaultTools: [search],
      defaultMiddleware: subagentMiddleware,   // ← 서브에이전트에도 파일시스템 (8-6)
      subagents: [
        {
          name: "researcher",
          description: "언어 하나를 조사해 3줄 요약을 반환합니다.",
          systemPrompt: "search 로 조사하고 3줄로 요약하세요. NOT_FOUND 면 '자료 없음' 이라고만 답하세요.",
          tools: [search],
        },
      ],
      generalPurposeAgent: false,              // general-purpose 는 안 쓴다 (토큰 절약)
    }),
    anthropicPromptCachingMiddleware({ unsupportedModelBehavior: "ignore", minMessagesToCache: 1 }),
  ],
}).withConfig({ recursionLimit: 10000 });

const result = await agent.invoke({
  messages: [{ role: "user", content: "Rust 와 Go 와 Zig 를 비교 조사해줘." }],
});

createDeepAgent(params)
  ≡ createAgent({
      model, systemPrompt: prefix+base+suffix, tools, middleware: [기본 스택], ...
    }).withConfig({ recursionLimit: 10000 })

/**
 * Step 08 — 미들웨어 조합
 * 실행: npx tsx docs/reference/deepagent/step-08-middleware/practice.ts
 *
 * 검증 버전: deepagents 1.11.0 / langchain 1.5.3 / @langchain/anthropic 1.5.1
 *
 * 이 파일은 본문 8-1 ~ 8-8 의 예제를 순서대로 담고 있습니다.
 * 핵심 메시지: createDeepAgent 를 벗기면 createAgent + 미들웨어 스택이다.
 *
 * 필요 환경변수: ANTHROPIC_API_KEY
 *   (OpenAI 를 쓰려면 MODEL 을 "openai:gpt-5.5" 로 바꾸고 OPENAI_API_KEY 를 설정하세요.
 *    단 8-7 의 프롬프트 캐싱은 Anthropic/Bedrock 전용입니다.)
 */
import "dotenv/config";
import {
  createDeepAgent,
  createFilesystemMiddleware,
  createSubAgentMiddleware,
  createSummarizationMiddleware,
  createPatchToolCallsMiddleware,
  createMemoryMiddleware,
  StateBackend,
  TASK_SYSTEM_PROMPT,
} from "deepagents";
import {
  createAgent,
  createMiddleware,
  todoListMiddleware,
  anthropicPromptCachingMiddleware,
  summarizationMiddleware,
  tool,
} from "langchain";
import * as z from "zod";

const MODEL = "anthropic:claude-sonnet-4-6";

/* ===== 공용 준비물 ===== */

/**
 * 모델 호출 직전의 request 를 훔쳐보는 스파이.
 * request.tools 로 **모델에게 실제로 보이는 도구 목록**을,
 * request.systemMessage.text 로 최종 시스템 프롬프트를 봅니다.
 * (Step 07 의 makePromptSpy 를 도구까지 보도록 확장한 것)
 */
function makeInspector(label: string, sink?: { tools?: string[]; prompt?: string }) {
  let done = false;
  return createMiddleware({
    name: "InspectorMiddleware",
    wrapModelCall: async (request, handler) => {
      if (!done) {
        done = true;
        const toolNames = request.tools.map((t: any) => t.name).sort();
        const prompt = request.systemMessage.text ?? "";
        if (sink) {
          sink.tools = toolNames;
          sink.prompt = prompt;
        }
        console.log(`\n--- [${label}] ---`);
        console.log(`도구(${toolNames.length}): ${toolNames.join(", ")}`);
        console.log(`프롬프트 길이: ${prompt.length}`);
        console.log(
          `섹션: base=${prompt.includes("You are a Deep Agent")} ` +
            `fs=${prompt.includes("## Filesystem Tools")} ` +
            `task=${prompt.includes("subagent spawner")}`,
        );
      }
      return handler(request);
    },
  });
}

const getWeather = tool(({ city }: { city: string }) => `${city} 는 맑음, 21도.`, {
  name: "get_weather",
  description: "도시의 현재 날씨를 조회합니다.",
  schema: z.object({ city: z.string().describe("도시 이름") }),
});

/* ===== [8-1] createDeepAgent 의 기본 미들웨어 스택 정체 밝히기 ===== */
/**
 * createDeepAgent 는 마법이 아닙니다. 내부적으로 이 순서의 미들웨어 스택을 조립한 뒤
 * createAgent 에 넘길 뿐입니다 (deepagents@1.11.0 소스 기준):
 *
 *   [기본 세그먼트]
 *     1. todoListMiddleware()                    ← langchain 제공
 *     2. createSkillsMiddleware(...)             ← skills 를 줬을 때만
 *     3. createFilesystemMiddleware({ backend, permissions, tools })
 *     4. createSubAgentMiddleware({ defaultModel, defaultTools, subagents, ... })
 *     5. createSummarizationMiddleware({ backend })
 *     6. createPatchToolCallsMiddleware()
 *     7. createAsyncSubAgentMiddleware(...)      ← 비동기 서브에이전트를 줬을 때만
 *   [내 middleware 옵션이 여기 끼어든다]
 *   [꼬리 세그먼트]
 *     8. 하네스 프로파일의 extraMiddleware
 *     9. anthropicPromptCachingMiddleware() + CacheBreakpointMiddleware  ← Anthropic 모델일 때
 *        bedrockPromptCachingMiddleware()                                ← Bedrock 모델일 때
 *    10. createMemoryMiddleware({ backend, sources: memory })            ← memory 를 줬을 때만
 *    11. humanInTheLoopMiddleware({ interruptOn })                       ← interruptOn 을 줬을 때만
 *
 * 그리고 마지막에:
 *   return createAgent({ model, systemPrompt, tools, middleware, ... })
 *            .withConfig({ recursionLimit: 10000, metadata: { ls_integration: "deepagents" } });
 *
 * 즉 createDeepAgent === createAgent + 위 스택 + 프롬프트 조립 + recursionLimit 1만.
 */
async function step8_1() {
  console.log("\n########## [8-1] createDeepAgent 의 정체 ##########");

  const agent = await createDeepAgent({
    model: MODEL,
    tools: [getWeather],
    systemPrompt: "당신은 날씨 봇입니다.",
    middleware: [makeInspector("createDeepAgent 기본")],
  });

  await agent.invoke({ messages: [{ role: "user", content: "안녕" }] });
  // 도구 목록에 내가 준 get_weather 말고도
  // write_todos / ls / read_file / write_file / edit_file / glob / grep / task 가 보입니다.
  // 전부 미들웨어가 등록한 것입니다.
}

/* ===== [8-2] deepagents 가 export 하는 미들웨어들 ===== */
/**
 * 각 팩토리를 직접 만들어서 .name 을 찍어봅니다.
 * ⚠️ .name 이 표기와 다른 것들이 있습니다 (subAgentMiddleware 는 소문자 s!).
 *    이 이름이 8-5 의 "이름 충돌" 규칙에서 결정적입니다.
 */
async function step8_2() {
  console.log("\n########## [8-2] 미들웨어 카탈로그 ##########");

  // StateBackend 는 런타임 state 가 필요하므로 팩토리 형태로 넘깁니다.
  // createDeepAgent 의 기본값도 정확히 이것입니다: (config) => new StateBackend(config)
  const backend = (config: { state: unknown; store?: any }) => new StateBackend(config);

  const list = [
    todoListMiddleware(),
    createFilesystemMiddleware({ backend }),
    createSubAgentMiddleware({ defaultModel: MODEL }),
    createSummarizationMiddleware({ backend }),
    createPatchToolCallsMiddleware(),
    createMemoryMiddleware({ backend, sources: ["/AGENTS.md"] }),
    anthropicPromptCachingMiddleware({ unsupportedModelBehavior: "ignore" }),
    summarizationMiddleware({ model: MODEL }), // ← langchain 쪽. 이름을 잘 보세요.
  ];

  for (const m of list) {
    const tools = (m as any).tools?.map((t: any) => t.name) ?? [];
    console.log(`${m.name.padEnd(28)} 등록 도구: ${tools.length ? tools.join(", ") : "(없음)"}`);
  }

  // 출력을 보면 deepagents 의 createSummarizationMiddleware 와
  // langchain 의 summarizationMiddleware 가 **같은 이름**("SummarizationMiddleware")입니다.
  // 8-5 의 함정이 여기서 시작됩니다.
}

/* ===== [8-3] 직접 조립 — createDeepAgent 와 동등한 것 만들기 ===== */
/**
 * 8-1 의 스택을 손으로 쌓아 createAgent 에 넣습니다.
 * 두 에이전트의 **도구 목록**을 비교해 동등한지 확인합니다.
 *
 * ⚠️ 한 가지는 재현할 수 없습니다: 내장 BASE_AGENT_PROMPT 는 export 되지 않습니다.
 *    (TASK_SYSTEM_PROMPT, DEFAULT_SUBAGENT_PROMPT 는 export 됩니다)
 *    그래서 base 프롬프트는 내가 직접 써 넣어야 합니다 — 이것이 직접 조립의 비용입니다.
 */
async function step8_3() {
  console.log("\n########## [8-3] 직접 조립 ##########");

  const backend = (config: { state: unknown; store?: any }) => new StateBackend(config);
  const tools = [getWeather];

  const deepSink: { tools?: string[]; prompt?: string } = {};
  const manualSink: { tools?: string[]; prompt?: string } = {};

  // (A) createDeepAgent
  const deep = await createDeepAgent({
    model: MODEL,
    tools,
    systemPrompt: "당신은 날씨 봇입니다.",
    middleware: [makeInspector("A. createDeepAgent", deepSink)],
  });
  await deep.invoke({ messages: [{ role: "user", content: "안녕" }] });

  // (B) createAgent + 미들웨어 스택 직접 조립
  const manual = createAgent({
    model: MODEL,
    tools,
    systemPrompt: "당신은 날씨 봇입니다.", // ← createDeepAgent 와 달리 이건 '교체'다 (Step 07 참고)
    middleware: [
      todoListMiddleware(),
      createFilesystemMiddleware({ backend }),
      createSubAgentMiddleware({
        defaultModel: MODEL,
        defaultTools: tools,
        subagents: [],
        // createDeepAgent 는 general-purpose 를 subagents 배열에 직접 넣고 여기선 false 로 끕니다.
        // 직접 조립할 땐 true 로 두면 이 미들웨어가 general-purpose 를 만들어 줍니다.
        generalPurposeAgent: true,
      }),
      createSummarizationMiddleware({ backend }),
      createPatchToolCallsMiddleware(),
      anthropicPromptCachingMiddleware({
        unsupportedModelBehavior: "ignore",
        minMessagesToCache: 1,
      }),
      makeInspector("B. 직접 조립", manualSink),
    ],
  }).withConfig({ recursionLimit: 10000 });

  await manual.invoke({ messages: [{ role: "user", content: "안녕" }] });

  // 비교
  const a = new Set(deepSink.tools ?? []);
  const b = new Set(manualSink.tools ?? []);
  const onlyA = [...a].filter((x) => !b.has(x));
  const onlyB = [...b].filter((x) => !a.has(x));

  console.log("\n===== 동등성 비교 =====");
  console.log("도구 집합 동일:", onlyA.length === 0 && onlyB.length === 0);
  console.log("createDeepAgent 에만:", onlyA);
  console.log("직접 조립에만:", onlyB);
  console.log(
    `프롬프트 길이: createDeepAgent=${deepSink.prompt?.length} 직접조립=${manualSink.prompt?.length}`,
  );
  console.log(
    "→ 도구는 같지만 프롬프트가 짧습니다. BASE_AGENT_PROMPT 가 빠졌기 때문입니다.",
  );
}

/* ===== [8-4] 필요한 기능만 빌려쓰기 ===== */
/**
 * Deep Agent 전체가 필요한 게 아니라 조각만 필요할 때가 많습니다.
 * 미들웨어는 개별로 export 되어 있으므로 평범한 createAgent 에 원하는 것만 꽂으면 됩니다.
 */
async function step8_4() {
  console.log("\n########## [8-4] 필요한 것만 빌려쓰기 ##########");

  const backend = (config: { state: unknown; store?: any }) => new StateBackend(config);

  // (A) 파일시스템만 — 서브에이전트도 todo 도 없는 "메모장 달린 에이전트"
  const fsOnly = createAgent({
    model: MODEL,
    systemPrompt: "당신은 메모 도우미입니다. 요청받은 내용을 /notes/ 아래 파일로 정리하세요.",
    middleware: [createFilesystemMiddleware({ backend }), makeInspector("A. 파일시스템만")],
  });

  const r1 = await fsOnly.invoke({
    messages: [{ role: "user", content: "오늘 회의 결론 '배포는 금요일'을 메모해줘." }],
  });
  console.log("생성된 파일:", Object.keys((r1 as any).files ?? {}));

  // (B) 계획만 — write_todos 만 있는 에이전트
  const planOnly = createAgent({
    model: MODEL,
    tools: [getWeather],
    systemPrompt: "당신은 여행 플래너입니다.",
    middleware: [todoListMiddleware(), makeInspector("B. 계획만")],
  });

  const r2 = await planOnly.invoke({
    messages: [
      { role: "user", content: "서울, 부산, 제주 날씨를 확인하고 여행지를 추천하는 계획을 세워줘." },
    ],
  });
  console.log("todos:", JSON.stringify((r2 as any).todos ?? [], null, 2));

  // (C) 읽기 전용 파일시스템 — tools 화이트리스트로 도구를 줄이면 프롬프트 지침도 같이 줄어듭니다.
  const readOnly = createAgent({
    model: MODEL,
    systemPrompt: "당신은 코드 탐색기입니다. 파일을 수정하지 마세요.",
    middleware: [
      createFilesystemMiddleware({ backend, tools: ["read_file", "ls", "glob", "grep"] }),
      makeInspector("C. 읽기 전용 fs"),
    ],
  });
  await readOnly.invoke({ messages: [{ role: "user", content: "안녕" }] });
  // 도구 목록에 write_file / edit_file 이 없고,
  // "## Filesystem Tools" 헤더의 나열도 4개로 줄어든 것을 확인하세요.
}

/* ===== [8-5] createDeepAgent 에 middleware 추가 — 더하기인가 대체인가 ===== */
/**
 * 정답: **더하기**. 단, **이름이 같으면 대체**입니다.
 *
 * 내부의 mergeMiddlewareStack 규칙 (deepagents@1.11.0):
 *   - 기본/꼬리 세그먼트에 **같은 이름**이 있으면 → 그 자리에서 **교체**
 *   - 이름이 새로우면 → 기본 세그먼트와 꼬리 세그먼트 **사이에 삽입**
 */
async function step8_5() {
  console.log("\n########## [8-5] middleware 옵션: 추가 vs 교체 ##########");

  // (A) 새 이름 → 추가된다. 기본 스택은 그대로.
  let toolCallCount = 0;
  const logging = createMiddleware({
    name: "LogToolCallsMiddleware",
    wrapToolCall: async (request, handler) => {
      toolCallCount += 1;
      console.log(`  [로그] #${toolCallCount} ${request.toolCall.name}`);
      return handler(request);
    },
  });

  const added = await createDeepAgent({
    model: MODEL,
    tools: [getWeather],
    systemPrompt: "당신은 날씨 봇입니다.",
    middleware: [logging, makeInspector("A. 커스텀 추가")],
  });
  await added.invoke({ messages: [{ role: "user", content: "서울 날씨 알려줘." }] });
  console.log("→ 기본 스택(파일/task 도구)이 그대로 남아있는지 위 도구 목록을 확인하세요.");

  // (B) 이름이 겹치면 → 교체된다. 이게 함정입니다.
  //     langchain 의 summarizationMiddleware 의 name 도 "SummarizationMiddleware" 입니다.
  //     deepagents 의 createSummarizationMiddleware 와 **이름이 같습니다.**
  //     따라서 아래는 "요약 미들웨어를 추가" 가 아니라 "deepagents 요약을 **교체**" 입니다.
  //     → 대화 기록을 /conversation_history 에 오프로드하는 기능을 잃습니다.
  const replaced = await createDeepAgent({
    model: MODEL,
    tools: [getWeather],
    systemPrompt: "당신은 날씨 봇입니다.",
    middleware: [
      summarizationMiddleware({ model: MODEL, maxTokensBeforeSummary: 1000 }),
      makeInspector("B. 이름 충돌"),
    ],
  });
  await replaced.invoke({ messages: [{ role: "user", content: "안녕" }] });
  console.log("→ 에러 없이 조용히 교체되었습니다. 8-6 에서 결과를 봅니다.");
}

/* ===== [8-6] 미들웨어 순서 문제 ===== */
/**
 * 순서가 중요한 이유 두 가지.
 *
 * 1) 훅 실행 순서
 *    - before* / wrap* 은 배열 **앞** 미들웨어가 **바깥**(먼저 실행)
 *    - after* 는 **뒤** 미들웨어가 먼저 실행 (양파 껍질처럼 감싼다)
 *    프롬프트를 덧붙이는 미들웨어는 앞에 둘수록 프롬프트 **앞쪽**에 붙습니다.
 *
 * 2) 서브에이전트는 부모의 미들웨어 배열을 **상속하지 않는다**
 *    서브에이전트의 미들웨어는 createSubAgentMiddleware 의
 *    defaultMiddleware / generalPurposeMiddleware 옵션으로만 정해집니다.
 *    직접 조립하면서 이걸 안 주면 서브에이전트는 **파일 도구 없이** 태어납니다.
 */
async function step8_6() {
  console.log("\n########## [8-6] 순서와 상속 ##########");

  const backend = (config: { state: unknown; store?: any }) => new StateBackend(config);

  // (1) 훅 순서 확인 — 세 미들웨어가 프롬프트에 마커를 덧붙입니다.
  const marker = (n: string) =>
    createMiddleware({
      name: `Marker${n}Middleware`,
      wrapModelCall: async (request, handler) => {
        console.log(`  들어감: ${n}`);
        const r = await handler({
          ...request,
          systemMessage: request.systemMessage.concat(`\n[${n}]`),
        });
        console.log(`  나옴:   ${n}`);
        return r;
      },
    });

  const ordered = createAgent({
    model: MODEL,
    systemPrompt: "짧게 답하세요.",
    middleware: [marker("첫째"), marker("둘째"), marker("셋째")],
  });
  await ordered.invoke({ messages: [{ role: "user", content: "안녕" }] });
  console.log("→ 들어감: 첫째→둘째→셋째, 나옴: 셋째→둘째→첫째 (양파 구조)");

  // (2) 서브에이전트 미들웨어 상속 — 틀린 조립
  console.log("\n[틀린 조립] 서브에이전트에 defaultMiddleware 를 안 줌");
  const wrong = createAgent({
    model: MODEL,
    middleware: [
      createFilesystemMiddleware({ backend }), // ← 부모에게만 파일 도구가 생긴다
      createSubAgentMiddleware({
        defaultModel: MODEL,
        subagents: [
          {
            name: "note-taker",
            description: "받은 내용을 /notes.md 에 저장하는 서브에이전트",
            systemPrompt: "받은 내용을 /notes.md 에 write_file 로 저장하세요.",
          },
        ],
        generalPurposeAgent: false,
      }),
    ],
    systemPrompt: "note-taker 서브에이전트에게 위임하세요.",
  });

  const wrongResult = await wrong.invoke({
    messages: [{ role: "user", content: "'배포는 금요일' 을 note-taker 에게 저장시켜줘." }],
  });
  console.log("결과:", wrongResult.messages.at(-1)?.text?.slice(0, 200));
  console.log("파일:", Object.keys((wrongResult as any).files ?? {}));
  console.log("→ 서브에이전트에 write_file 이 없어 실패하거나 엉뚱하게 답합니다.");

  // (3) 올바른 조립 — defaultMiddleware 로 서브에이전트에게도 파일시스템을 준다
  console.log("\n[올바른 조립] defaultMiddleware 로 파일시스템 전달");
  const right = createAgent({
    model: MODEL,
    middleware: [
      createFilesystemMiddleware({ backend }),
      createSubAgentMiddleware({
        defaultModel: MODEL,
        defaultMiddleware: [createFilesystemMiddleware({ backend })], // ← 이 한 줄이 핵심
        subagents: [
          {
            name: "note-taker",
            description: "받은 내용을 /notes.md 에 저장하는 서브에이전트",
            systemPrompt: "받은 내용을 /notes.md 에 write_file 로 저장하세요.",
          },
        ],
        generalPurposeAgent: false,
      }),
    ],
    systemPrompt: "note-taker 서브에이전트에게 위임하세요.",
  });

  const rightResult = await right.invoke({
    messages: [{ role: "user", content: "'배포는 금요일' 을 note-taker 에게 저장시켜줘." }],
  });
  console.log("결과:", rightResult.messages.at(-1)?.text?.slice(0, 200));
  console.log("파일:", Object.keys((rightResult as any).files ?? {}));

  // 참고: createDeepAgent 를 쓰면 이 배선을 자동으로 해 줍니다.
  //       normalizeSubagentSpec 이 서브에이전트마다
  //       [todoList, filesystem, summarization, patchToolCalls] 를 깔아줍니다.
}

/* ===== [8-7] 캐싱 미들웨어 (provider 프롬프트 캐싱) ===== */
/**
 * Deep Agent 의 시스템 프롬프트는 5천 자가 넘습니다(Step 07). 매 턴 다시 보냅니다.
 * Anthropic/Bedrock 의 프롬프트 캐싱은 이 앞부분을 재사용해 입력 토큰 비용을 줄입니다.
 *
 * createDeepAgent 는 Anthropic 모델이면 이걸 **자동으로** 붙입니다:
 *   anthropicPromptCachingMiddleware({ unsupportedModelBehavior: "ignore", minMessagesToCache: 1 })
 *   + 내부 CacheBreakpointMiddleware
 * Bedrock 이면 bedrockPromptCachingMiddleware({ unsupportedModelBehavior: "ignore" }).
 *
 * 즉 createDeepAgent 를 쓰면 캐싱은 공짜입니다. 직접 조립할 때만 신경 쓰면 됩니다.
 */
async function step8_7() {
  console.log("\n########## [8-7] 프롬프트 캐싱 ##########");

  // usage_metadata 로 캐시 읽기/쓰기 토큰을 확인합니다.
  const usageSpy = createMiddleware({
    name: "UsageSpyMiddleware",
    afterModel: async (state) => {
      const last = state.messages.at(-1) as any;
      const u = last?.usage_metadata;
      if (u) {
        console.log(
          `  입력=${u.input_tokens} 출력=${u.output_tokens} ` +
            `캐시생성=${u.input_token_details?.cache_creation ?? 0} ` +
            `캐시읽기=${u.input_token_details?.cache_read ?? 0}`,
        );
      }
      return undefined;
    },
  });

  const agent = await createDeepAgent({
    model: MODEL,
    tools: [getWeather],
    systemPrompt: "당신은 날씨 봇입니다.",
    middleware: [usageSpy],
  });

  console.log("1회차 (캐시 생성):");
  const r1 = await agent.invoke({ messages: [{ role: "user", content: "서울 날씨?" }] });

  console.log("2회차 (캐시 읽기 — 같은 대화를 이어감):");
  await agent.invoke({
    messages: [...r1.messages, { role: "user", content: "부산은?" }],
  });

  // 캐시읽기 값이 0보다 커지면 성공입니다.
  // 캐시는 기본 5분 TTL 이고, 프롬프트 앞부분이 **바이트 단위로 동일**해야 적중합니다.
}

/* ===== [8-8] 종합 — 최소 Deep Agent 를 직접 조립 ===== */
/**
 * "파일시스템 + 계획 + 서브에이전트" 만 있는 경량 리서치 에이전트.
 * 요약/패치/캐싱은 뺐습니다. 무엇을 얻고 무엇을 잃는지 주석으로 정리했습니다.
 */
async function step8_8() {
  console.log("\n########## [8-8] 종합: 최소 조립 ##########");

  const backend = (config: { state: unknown; store?: any }) => new StateBackend(config);

  const search = tool(
    ({ query }: { query: string }) => {
      const db: Record<string, string> = {
        rust: "Rust 는 2015년 1.0 출시. 소유권 시스템으로 메모리 안전을 보장.",
        go: "Go 는 2012년 1.0 출시. 고루틴 기반 동시성이 특징.",
      };
      const hit = Object.entries(db).find(([k]) => query.toLowerCase().includes(k));
      return hit ? hit[1] : "NOT_FOUND";
    },
    {
      name: "search",
      description: "프로그래밍 언어 정보를 검색합니다.",
      schema: z.object({ query: z.string() }),
    },
  );

  const subagentMiddleware = [
    createFilesystemMiddleware({ backend }),
    createPatchToolCallsMiddleware(),
  ];

  const agent = createAgent({
    model: MODEL,
    tools: [search],
    systemPrompt: `당신은 언어 리서처입니다.

## 워크플로
1. 조사할 언어가 2개 이상이면 write_todos 로 계획을 세운다.
2. 각 언어는 researcher 서브에이전트에게 task 로 위임한다.
3. 결과를 /report.md 에 write_file 로 저장한다.

## 도구 사용 규칙
- search 가 "NOT_FOUND" 를 반환하면 "자료 없음" 으로 표기한다. 지어내지 않는다.
- 파일 경로는 항상 /로 시작한다.

## 중단 조건
- /report.md 를 쓴 뒤 즉시 종료한다.

${TASK_SYSTEM_PROMPT}`, // ← 내장 task 지침을 재사용. export 되어 있어 그대로 쓸 수 있다.
    middleware: [
      todoListMiddleware(),
      createFilesystemMiddleware({ backend }),
      createSubAgentMiddleware({
        defaultModel: MODEL,
        defaultTools: [search],
        defaultMiddleware: subagentMiddleware, // ← 서브에이전트에도 파일시스템을 준다 (8-6)
        subagents: [
          {
            name: "researcher",
            description: "언어 하나를 조사해 3줄 요약을 반환합니다.",
            systemPrompt: "search 로 조사하고 3줄로 요약하세요. NOT_FOUND 면 '자료 없음' 이라고만 답하세요.",
            tools: [search],
          },
        ],
        generalPurposeAgent: false, // general-purpose 는 안 쓴다 (토큰 절약)
      }),
      anthropicPromptCachingMiddleware({ unsupportedModelBehavior: "ignore", minMessagesToCache: 1 }),
      makeInspector("8-8 최소 조립"),
    ],
  }).withConfig({ recursionLimit: 10000 });

  const result = await agent.invoke({
    messages: [{ role: "user", content: "Rust 와 Go 와 Zig 를 비교 조사해줘." }],
  });

  console.log("\n최종 응답:", result.messages.at(-1)?.text);
  console.log("파일:", Object.keys((result as any).files ?? {}));

  // 얻은 것: 스택이 명시적이라 읽힌다. 요약 미들웨어가 없어 대화가 잘리지 않는다.
  // 잃은 것:
  //   - BASE_AGENT_PROMPT (직접 써야 함)
  //   - 긴 대화에서의 자동 요약/오프로드 → 컨텍스트 초과 시 에러
  //   - patchToolCalls 를 부모에 안 넣었으므로 도구 호출 짝이 깨지면 provider 에러
  //   - 프로파일/권한/HITL 배선
  // → 대부분의 경우 createDeepAgent + middleware 옵션이 정답입니다.
}

/* ===== 실행 ===== */
async function main() {
  await step8_1();
  await step8_2();
  await step8_3();
  await step8_4();
  await step8_5();
  await step8_6();
  await step8_7();
  await step8_8();
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

/**
 * Step 08 — 미들웨어 조합 · 연습문제
 * 실행: npx tsx docs/reference/deepagent/step-08-middleware/exercise.ts
 *
 * 각 [문제 N] 블록 아래를 직접 채우세요.
 * 정답은 solution.ts 에 있습니다. 먼저 스스로 풀어보고 여세요.
 *
 * 필요 환경변수: ANTHROPIC_API_KEY
 */
import "dotenv/config";
import {
  createDeepAgent,
  createFilesystemMiddleware,
  createSubAgentMiddleware,
  createSummarizationMiddleware,
  createPatchToolCallsMiddleware,
  StateBackend,
} from "deepagents";
import {
  createAgent,
  createMiddleware,
  todoListMiddleware,
  anthropicPromptCachingMiddleware,
  summarizationMiddleware,
  tool,
} from "langchain";
import * as z from "zod";

const MODEL = "anthropic:claude-sonnet-4-6";

/* ===== 공용 준비물 (그대로 쓰세요) ===== */

/**
 * 모델 호출 직전의 도구 목록과 시스템 프롬프트를 훔쳐봅니다.
 * sink 를 넘기면 결과를 바깥으로 빼낼 수 있습니다.
 * ⚠️ 미들웨어 배열의 **맨 뒤**에 두세요. 앞에 두면 다른 미들웨어가
 *    프롬프트를 덧붙이기 전을 보게 됩니다.
 */
function makeInspector(label: string, sink?: { tools?: string[]; prompt?: string }) {
  let done = false;
  return createMiddleware({
    name: "InspectorMiddleware",
    wrapModelCall: async (request, handler) => {
      if (!done) {
        done = true;
        const toolNames = request.tools.map((t: any) => t.name).sort();
        const prompt = request.systemMessage.text ?? "";
        if (sink) {
          sink.tools = toolNames;
          sink.prompt = prompt;
        }
        console.log(`[${label}] 도구(${toolNames.length}): ${toolNames.join(", ")}`);
        console.log(`[${label}] 프롬프트 길이: ${prompt.length}`);
      }
      return handler(request);
    },
  });
}

/** StateBackend 는 런타임 state 가 필요하므로 팩토리로 넘깁니다. */
const backend = (config: { state: unknown; store?: any }) => new StateBackend(config);

const saveNote = tool(({ text }: { text: string }) => `메모함: ${text}`, {
  name: "save_note",
  description: "메모를 저장합니다.",
  schema: z.object({ text: z.string() }),
});

/* ===== [문제 1] =====
 * createDeepAgent 에 도구를 **하나도 주지 말고**(tools 생략) 인스펙터를 붙여
 * 모델에게 보이는 도구 목록을 출력하세요.
 *
 * 몇 개가 나오나요? 각 도구가 어느 미들웨어에서 온 것인지 주석으로 매핑하세요.
 */
async function ex1() {
  console.log("\n===== [문제 1] =====");
  // 여기에 작성
  // → 매핑:
  //   write_todos                                    ← ?
  //   ls, read_file, write_file, edit_file, glob, grep ← ?
  //   task                                           ← ?
}

/* ===== [문제 2] =====
 * createDeepAgent 에 `name: "read_file"` 인 커스텀 도구를 주고
 * try/catch 로 감싸 실행하세요.
 *
 * 무슨 일이 일어나는지 출력하고, 왜 그런지 주석으로 설명하세요.
 * (에러가 나는 것이 정답입니다 — 어떤 에러가 **어느 시점에** 나는지가 답입니다)
 */
async function ex2() {
  console.log("\n===== [문제 2] =====");
  // 여기에 작성
  // → 왜 그런가:
  // → 에러가 나는 시점은 createDeepAgent 호출 시점인가, invoke 시점인가?
}

/* ===== [문제 3] =====
 * 아래 미들웨어들을 각각 만들어 **.name 을 전부 출력**하세요. (API 호출 없음, 비용 0)
 *
 *   todoListMiddleware()                          (langchain)
 *   createFilesystemMiddleware({ backend })       (deepagents)
 *   createSubAgentMiddleware({ defaultModel })    (deepagents)
 *   createSummarizationMiddleware({ backend })    (deepagents)
 *   createPatchToolCallsMiddleware()              (deepagents)
 *   summarizationMiddleware({ model })            (langchain)
 *
 * 팩토리 이름과 .name 이 다른 것을 찾아 주석에 표로 정리하세요.
 * 특히 **두 패키지의 미들웨어 중 .name 이 같은 쌍**을 찾으세요 — 문제 6 의 전제입니다.
 */
async function ex3() {
  console.log("\n===== [문제 3] =====");
  // 여기에 작성
  // → 팩토리 이름 != .name 인 것:
  // → .name 이 같은 쌍:
}

/* ===== [문제 4] =====
 * createAgent + 미들웨어로 createDeepAgent 와 **도구 집합이 동일한** 에이전트를 조립하세요.
 *
 * 두 도구 집합의 차집합을 **양방향으로** 출력해 [] , [] 가 나오는 것을 보이세요.
 * (힌트: makeInspector 에 sink 를 넘기면 도구 목록을 바깥으로 빼낼 수 있습니다)
 *
 * 프롬프트 길이는 왜 다른가요? 주석으로 설명하세요.
 */
async function ex4() {
  console.log("\n===== [문제 4] =====");
  // 여기에 작성
  // → 프롬프트 길이가 다른 이유:
}

/* ===== [문제 5] =====
 * createFilesystemMiddleware({ backend, tools: ["ls", "glob"] }) 를 시도해 보세요.
 * (read_file 이 빠져 있습니다)
 *
 * 정상 동작하나요? try/catch 로 감싸 결과를 출력하고,
 * 문서상의 제약을 근거로 주석에 설명하세요.
 */
async function ex5() {
  console.log("\n===== [문제 5] =====");
  // 여기에 작성
  // → 왜 read_file 은 필수인가:
}

/* ===== [문제 6] =====
 * createDeepAgent 에 다음 둘을 각각 넣고 도구 목록을 비교하세요.
 *   (a) 새 이름의 커스텀 미들웨어 (예: name: "MyAuditMiddleware")
 *   (b) name: "SummarizationMiddleware" 인 커스텀 미들웨어
 *
 * (b) 에서 **아무 에러도 안 나는 것**을 확인하고,
 * 실제로 무엇이 교체되었는지 주석으로 설명하세요.
 * (힌트: mergeMiddlewareStack 의 병합 키는 무엇인가?)
 */
async function ex6() {
  console.log("\n===== [문제 6] =====");
  // 여기에 작성
  // → (b) 에서 실제로 교체된 것:
  // → 그 대가는 무엇인가:
}

/* ===== [문제 7] =====
 * createAgent 로 서브에이전트를 가진 에이전트를 **두 벌** 만드세요.
 *   (a) createSubAgentMiddleware 에 defaultMiddleware 를 준 것
 *   (b) 안 준 것
 *
 * 서브에이전트에게 "/notes.md 에 저장" 을 시키고 두 결과의
 * state.files 를 비교하세요.
 *
 * ⚠️ 모델의 응답 텍스트가 아니라 **files 목록**을 보세요. 왜일까요?
 */
async function ex7() {
  console.log("\n===== [문제 7] =====");
  // 여기에 작성
  // → 응답 텍스트를 믿으면 안 되는 이유:
}

/* ===== [문제 8] =====
 * (a) usage_metadata 스파이를 붙여 Anthropic 모델로 2턴 대화를 돌리고
 *     2회차에 cache_read 가 0보다 커지는 것을 확인하세요.
 *     (힌트: afterModel 훅에서 state.messages.at(-1).usage_metadata 를 보세요.
 *            필드는 input_token_details.cache_read / cache_creation 입니다)
 *
 * (b) 커스텀 미들웨어의 wrapModelCall 에서
 *     request.systemMessage.concat(`\n현재 시각: ${new Date().toISOString()}`)
 *     로 **매 요청 변하는 값**을 프롬프트에 주입하고, 다시 2턴을 돌려
 *     cache_read 가 어떻게 되는지 관찰하세요.
 *
 * 첫 번째 실행의 숫자를 메모해 두고 비교하세요.
 */
async function ex8() {
  console.log("\n===== [문제 8] =====");
  // 여기에 작성
  // → (b) 에서 cache_read 가 그렇게 되는 이유:
}

async function main() {
  await ex1();
  await ex2();
  await ex3();
  await ex4();
  await ex5();
  await ex6();
  await ex7();
  await ex8();
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

/**
 * Step 08 — 미들웨어 조합 · 정답
 * 실행: npx tsx docs/reference/deepagent/step-08-middleware/solution.ts
 *
 * exercise.ts 를 스스로 풀어본 뒤에 여세요.
 * 각 정답 위 주석에 기대 결과와 해설이 있습니다.
 */
import "dotenv/config";
import {
  createDeepAgent,
  createFilesystemMiddleware,
  createSubAgentMiddleware,
  createSummarizationMiddleware,
  createPatchToolCallsMiddleware,
  StateBackend,
} from "deepagents";
import {
  createAgent,
  createMiddleware,
  todoListMiddleware,
  anthropicPromptCachingMiddleware,
  summarizationMiddleware,
  tool,
} from "langchain";
import * as z from "zod";

const MODEL = "anthropic:claude-sonnet-4-6";

/* ===== 공용 준비물 ===== */

function makeInspector(label: string, sink?: { tools?: string[]; prompt?: string }) {
  let done = false;
  return createMiddleware({
    name: "InspectorMiddleware",
    wrapModelCall: async (request, handler) => {
      if (!done) {
        done = true;
        const toolNames = request.tools.map((t: any) => t.name).sort();
        const prompt = request.systemMessage.text ?? "";
        if (sink) {
          sink.tools = toolNames;
          sink.prompt = prompt;
        }
        console.log(`[${label}] 도구(${toolNames.length}): ${toolNames.join(", ")}`);
        console.log(`[${label}] 프롬프트 길이: ${prompt.length}`);
      }
      return handler(request);
    },
  });
}

const backend = (config: { state: unknown; store?: any }) => new StateBackend(config);

const saveNote = tool(({ text }: { text: string }) => `메모함: ${text}`, {
  name: "save_note",
  description: "메모를 저장합니다.",
  schema: z.object({ text: z.string() }),
});

/* ===== [정답 1] =====
 * 기대 결과: 도구 8개.
 *   edit_file, glob, grep, ls, read_file, task, write_file, write_todos
 *
 * → 매핑:
 *   write_todos                                       ← todoListMiddleware  (langchain)
 *   ls, read_file, write_file, edit_file, glob, grep  ← FilesystemMiddleware (deepagents)
 *   task                                              ← subAgentMiddleware   (deepagents)
 *
 * 해설: 도구를 하나도 안 줬는데 8개가 보입니다. createDeepAgent 는 "에이전트 생성기" 가
 * 아니라 "미들웨어 스택 조립기" 라는 것이 이 출력의 의미입니다.
 * execute 가 없는 이유는 기본 백엔드인 StateBackend 가 명령 실행을 지원하지 않아
 * 백엔드 능력 필터에서 제거되기 때문입니다 (Step 05 의 샌드박스 백엔드를 쓰면 나타납니다).
 */
async function sol1() {
  console.log("\n===== [정답 1] =====");
  const agent = await createDeepAgent({
    model: MODEL,
    systemPrompt: "당신은 도우미입니다.",
    middleware: [makeInspector("도구 없이 생성")],
  });
  await agent.invoke({ messages: [{ role: "user", content: "안녕" }] });
}

/* ===== [정답 2] =====
 * 기대 결과: ConfigurationError 를 던진다.
 *   Tool name(s) [read_file] conflict with built-in tools.
 *   Rename your custom tools to avoid this.
 *
 * → 왜 그런가: createDeepAgent 는 BUILTIN_TOOL_NAMES 집합
 *   (ls, read_file, write_file, edit_file, glob, grep, execute, task, write_todos
 *    + 비동기 태스크 도구들)과 내 도구 이름을 대조해 충돌하면 즉시 던집니다.
 *   조용히 덮어쓰면 "내 도구를 부른 줄 알았는데 내장 도구가 불렸다" 는
 *   최악의 디버깅이 되므로, 던지는 것이 옳은 설계입니다.
 *
 * → 에러 시점: **createDeepAgent 호출 시점**입니다. invoke 전에 터지므로
 *   API 호출 비용이 발생하지 않습니다. 부팅 시 검증되는 것과 같아서 좋습니다.
 */
async function sol2() {
  console.log("\n===== [정답 2] =====");
  const colliding = tool(({ path }: { path: string }) => `읽음: ${path}`, {
    name: "read_file", // ← 내장 도구와 충돌
    description: "내 방식대로 파일을 읽습니다.",
    schema: z.object({ path: z.string() }),
  });

  try {
    await createDeepAgent({
      model: MODEL,
      tools: [colliding],
      systemPrompt: "당신은 도우미입니다.",
    });
    console.log("생성 성공 — 예상과 다름!");
  } catch (err) {
    console.log("createDeepAgent 시점에 throw:", (err as Error).message);
    console.log("에러 타입:", (err as Error).constructor.name); // ConfigurationError
  }
}

/* ===== [정답 3] =====
 * 기대 출력:
 *   todoListMiddleware()                     → todoListMiddleware
 *   createFilesystemMiddleware()             → FilesystemMiddleware
 *   createSubAgentMiddleware()               → subAgentMiddleware        ← 소문자 s!
 *   createSummarizationMiddleware()          → SummarizationMiddleware
 *   createPatchToolCallsMiddleware()         → patchToolCallsMiddleware  ← 소문자 p!
 *   summarizationMiddleware()   [langchain]  → SummarizationMiddleware   ← 위와 같음!
 *
 * → 팩토리 이름 != .name 인 것: 전부. create 접두사가 빠지고, 대소문자도 일관성이 없습니다.
 *   특히 subAgentMiddleware / patchToolCallsMiddleware 는 **소문자로 시작**합니다.
 *   REQUIRED_MIDDLEWARE_NAMES 에는 "SubAgentMiddleware"(대문자)로 적혀 있어 더 헷갈립니다.
 *
 * → .name 이 같은 쌍:
 *   deepagents 의 createSummarizationMiddleware 와
 *   langchain 의 summarizationMiddleware 가 **둘 다 "SummarizationMiddleware"**.
 *   미들웨어 병합 키가 .name 문자열이므로, 이 둘은 서로를 교체합니다. → 정답 6
 *
 * 해설: 이 문제는 API 를 호출하지 않아 비용이 0입니다.
 * 미들웨어 이름을 추측하지 말고 **항상 찍어서 확인**하는 습관을 들이세요.
 */
async function sol3() {
  console.log("\n===== [정답 3] =====");
  const entries: [string, { name: string }][] = [
    ["todoListMiddleware()            [langchain] ", todoListMiddleware()],
    ["createFilesystemMiddleware()    [deepagents]", createFilesystemMiddleware({ backend })],
    ["createSubAgentMiddleware()      [deepagents]", createSubAgentMiddleware({ defaultModel: MODEL })],
    ["createSummarizationMiddleware() [deepagents]", createSummarizationMiddleware({ backend })],
    ["createPatchToolCallsMiddleware()[deepagents]", createPatchToolCallsMiddleware()],
    ["summarizationMiddleware()       [langchain] ", summarizationMiddleware({ model: MODEL })],
  ];

  for (const [factory, m] of entries) {
    console.log(`${factory} → ${m.name}`);
  }
}

/* ===== [정답 4] =====
 * 기대 결과: 도구 집합이 완전히 동일 (차집합 양방향 모두 []).
 *
 * → 프롬프트 길이가 다른 이유: 내장 BASE_AGENT_PROMPT 가 **export 되지 않기** 때문입니다.
 *   deepagents 는 TASK_SYSTEM_PROMPT, DEFAULT_SUBAGENT_PROMPT,
 *   DEFAULT_GENERAL_PURPOSE_DESCRIPTION, GENERAL_PURPOSE_SUBAGENT,
 *   REQUIRED_MIDDLEWARE_NAMES 는 export 하지만 BASE_AGENT_PROMPT 는 안 합니다.
 *   직접 조립하면 그 2천 자를 손으로 써야 합니다 — 이것이 직접 조립의 실질적 비용입니다.
 *
 * 해설: 도구가 같다는 것이 이 스텝의 증명입니다.
 *   createDeepAgent 는 마법이 아니라 createAgent + 미들웨어 스택 조립입니다.
 */
async function sol4() {
  console.log("\n===== [정답 4] =====");
  const tools = [saveNote];
  const deepSink: { tools?: string[]; prompt?: string } = {};
  const manualSink: { tools?: string[]; prompt?: string } = {};

  const deep = await createDeepAgent({
    model: MODEL,
    tools,
    systemPrompt: "당신은 메모 도우미입니다.",
    middleware: [makeInspector("A. createDeepAgent", deepSink)],
  });
  await deep.invoke({ messages: [{ role: "user", content: "안녕" }] });

  const manual = createAgent({
    model: MODEL,
    tools,
    systemPrompt: "당신은 메모 도우미입니다.",
    middleware: [
      todoListMiddleware(),
      createFilesystemMiddleware({ backend }),
      createSubAgentMiddleware({
        defaultModel: MODEL,
        defaultTools: tools,
        subagents: [],
        generalPurposeAgent: true,
      }),
      createSummarizationMiddleware({ backend }),
      createPatchToolCallsMiddleware(),
      anthropicPromptCachingMiddleware({
        unsupportedModelBehavior: "ignore",
        minMessagesToCache: 1,
      }),
      makeInspector("B. 직접 조립", manualSink),
    ],
  }).withConfig({ recursionLimit: 10000 });
  await manual.invoke({ messages: [{ role: "user", content: "안녕" }] });

  const a = new Set(deepSink.tools ?? []);
  const b = new Set(manualSink.tools ?? []);
  console.log("createDeepAgent 에만:", [...a].filter((x) => !b.has(x))); // []
  console.log("직접 조립에만:", [...b].filter((x) => !a.has(x))); // []
  console.log(
    `프롬프트 길이 차이: ${(deepSink.prompt?.length ?? 0) - (manualSink.prompt?.length ?? 0)}자 ` +
      `(= BASE_AGENT_PROMPT 분량)`,
  );
}

/* ===== [정답 5] =====
 * 기대 결과: read_file 이 없다는 취지의 에러가 발생합니다.
 *
 * → 왜 read_file 은 필수인가: 문서에 명시되어 있습니다 —
 *   "read_file must be included in every explicit array because it is used
 *    by normal file-inspection flows and by large-result recovery guidance."
 *
 *   FilesystemMiddleware 는 도구 결과가 toolTokenLimitBeforeEvict(기본 20000 토큰)를
 *   넘으면 그 결과를 **파일로 오프로드**하고, 모델에게 "이 경로를 read_file 로 읽어라" 는
 *   안내를 줍니다. read_file 이 없으면 이 복구 경로가 끊겨서 큰 결과가 그냥 사라집니다.
 *   그래서 화이트리스트에서 뺄 수 없게 막아둔 것입니다.
 *
 * 참고: 화이트리스트를 통과해도 **백엔드 능력 필터**가 한 번 더 거릅니다.
 *   tools 에 "execute" 를 넣어도 StateBackend 처럼 실행을 지원하지 않는 백엔드면
 *   조용히 빠집니다.
 */
async function sol5() {
  console.log("\n===== [정답 5] =====");
  try {
    const mw = createFilesystemMiddleware({ backend, tools: ["ls", "glob"] }); // read_file 없음
    console.log("생성됨. name:", mw.name);
    const agent = createAgent({
      model: MODEL,
      systemPrompt: "탐색기",
      middleware: [mw, makeInspector("read_file 없는 화이트리스트")],
    });
    await agent.invoke({ messages: [{ role: "user", content: "안녕" }] });
  } catch (err) {
    console.log("throw:", (err as Error).message);
  }

  // 올바른 사용: read_file 을 반드시 포함
  const ok = createFilesystemMiddleware({ backend, tools: ["read_file", "ls", "glob", "grep"] });
  const readOnly = createAgent({
    model: MODEL,
    systemPrompt: "탐색기",
    middleware: [ok, makeInspector("올바른 읽기 전용")],
  });
  await readOnly.invoke({ messages: [{ role: "user", content: "안녕" }] });
}

/* ===== [정답 6] =====
 * 기대 결과: (a) 와 (b) 모두 **도구 9개로 동일**하고 **에러가 없습니다.**
 *
 * → (b) 에서 실제로 교체된 것: deepagents 의 SummarizationMiddleware.
 *   mergeMiddlewareStack 의 병합 키는 **.name 문자열**입니다.
 *   내 커스텀 미들웨어의 name 이 "SummarizationMiddleware" 라서
 *   기본 세그먼트의 같은 이름 항목을 **그 자리에서 교체**했습니다.
 *   (a) 는 새 이름이라 기본 세그먼트와 꼬리 세그먼트 사이에 **삽입**되었습니다.
 *
 * → 그 대가: deepagents 의 요약 미들웨어는 잘라낸 대화를 backend 의
 *   /conversation_history 아래로 **오프로드**합니다. 교체하면 그 기능을 잃습니다.
 *   긴 리서치에서 요약이 트리거되면 에이전트가 자기가 만든 파일 경로를 잊고,
 *   최종 리포트에서 중간 산출물을 참조하지 못합니다.
 *   증상이 "가끔 결과가 부실함" 으로 나타나 추적이 매우 어렵습니다.
 *
 * 확인법: 대화를 길게 만들어(요약 트리거) state.files 에
 *   "/conversation_history..." 로 시작하는 키가 생기는지 보세요.
 *   교체한 쪽에서는 안 생깁니다.
 *
 * 교훈: 도구 목록이 같다고 스택이 같은 게 아닙니다.
 *   요약 미들웨어는 도구를 등록하지 않으므로 도구 목록으로는 교체를 감지할 수 없습니다.
 */
async function sol6() {
  console.log("\n===== [정답 6] =====");

  // (a) 새 이름 → 추가
  const audit = createMiddleware({
    name: "MyAuditMiddleware",
    wrapToolCall: async (request, handler) => {
      console.log(`  [감사] ${request.toolCall.name}`);
      return handler(request);
    },
  });
  const added = await createDeepAgent({
    model: MODEL,
    tools: [saveNote],
    systemPrompt: "메모 도우미",
    middleware: [audit, makeInspector("(a) 새 이름 → 추가")],
  });
  await added.invoke({ messages: [{ role: "user", content: "안녕" }] });

  // (b) 이름 충돌 → 조용한 교체. 에러 없음, 도구 목록 동일.
  const impostor = createMiddleware({
    name: "SummarizationMiddleware", // ← deepagents 것과 같은 이름
    beforeModel: async () => undefined, // 아무것도 안 함 = 요약 기능이 통째로 사라짐
  });
  const replaced = await createDeepAgent({
    model: MODEL,
    tools: [saveNote],
    systemPrompt: "메모 도우미",
    middleware: [impostor, makeInspector("(b) 이름 충돌 → 교체")],
  });
  await replaced.invoke({ messages: [{ role: "user", content: "안녕" }] });

  console.log("→ 에러도 없고 도구 목록도 같습니다. 그게 이 함정의 핵심입니다.");
}

/* ===== [정답 7] =====
 * 기대 결과:
 *   (a) defaultMiddleware 있음 → files: [ '/notes.md' ]
 *   (b) defaultMiddleware 없음 → files: []
 *
 * → 응답 텍스트를 믿으면 안 되는 이유:
 *   서브에이전트의 중간 과정은 부모에게 **보이지 않습니다** (Step 06).
 *   task 도구는 서브에이전트의 마지막 AI 메시지 텍스트만 부모에게 돌려줍니다.
 *   그래서 서브에이전트가 write_file 이 없어 실패해놓고 "저장했습니다" 라고
 *   보고하면, 부모는 그 말을 그대로 믿고 사용자에게 전달합니다.
 *   **관측 가능한 사실(state.files)만 믿으세요.** 이것이 서브에이전트 디버깅의 기본입니다.
 *
 * 해설: 부모의 middleware 배열은 부모에게만 적용됩니다.
 *   서브에이전트의 미들웨어는 createSubAgentMiddleware 의
 *   defaultMiddleware / generalPurposeMiddleware 로만 정해집니다.
 *   createDeepAgent 를 쓰면 이 배선을 자동으로 해 줍니다 —
 *   서브에이전트마다 [todoList, filesystem, summarization, patchToolCalls] 를 깔아줍니다.
 */
async function sol7() {
  console.log("\n===== [정답 7] =====");

  const makeAgent = (withDefaultMiddleware: boolean) =>
    createAgent({
      model: MODEL,
      middleware: [
        createFilesystemMiddleware({ backend }),
        createSubAgentMiddleware({
          defaultModel: MODEL,
          ...(withDefaultMiddleware
            ? { defaultMiddleware: [createFilesystemMiddleware({ backend })] }
            : {}),
          subagents: [
            {
              name: "note-taker",
              description: "받은 내용을 /notes.md 에 저장하는 서브에이전트",
              systemPrompt: "받은 내용을 /notes.md 에 write_file 로 저장하세요.",
            },
          ],
          generalPurposeAgent: false,
        }),
      ],
      systemPrompt: "note-taker 서브에이전트에게 task 로 위임하세요.",
    }).withConfig({ recursionLimit: 10000 });

  for (const [label, flag] of [
    ["(a) defaultMiddleware 있음", true],
    ["(b) defaultMiddleware 없음", false],
  ] as const) {
    const agent = makeAgent(flag);
    const r = await agent.invoke({
      messages: [{ role: "user", content: "'배포는 금요일' 을 note-taker 에게 저장시켜줘." }],
    });
    console.log(`\n--- ${label} ---`);
    console.log("모델의 말:", r.messages.at(-1)?.text?.slice(0, 120).replace(/\n/g, " "));
    console.log("실제 files:", Object.keys((r as any).files ?? {})); // ← 이것만 믿는다
  }
}

/* ===== [정답 8] =====
 * 기대 결과 (토큰 수는 매번 다릅니다. 필드명은 결정적입니다):
 *   (a) 1회차: 캐시생성>0, 캐시읽기=0
 *       2회차: 캐시읽기>0            ← 적중
 *   (b) 시각 주입 후: 매 요청 캐시생성만 발생, 캐시읽기=0 으로 붙박이
 *
 * → (b) 에서 cache_read 가 0인 이유: 프롬프트 캐싱은 **접두사가 바이트 단위로 동일**할 때만
 *   적중합니다. 시스템 프롬프트에 매 요청 변하는 타임스탬프가 들어가면 접두사가
 *   달라져 캐시가 전부 무효화됩니다.
 *
 * 중요: 캐시 미스는 공짜가 아닙니다. **캐시 쓰기는 일반 입력보다 비쌉니다.**
 *   즉 캐싱을 켜놓고 접두사를 매번 깨면 캐싱을 안 켠 것보다 **비용이 늘어납니다.**
 *   cache_read 가 계속 0이면 반드시 원인을 찾으세요.
 *
 * 참고: createDeepAgent 가 MemoryMiddleware 를 캐싱 미들웨어보다 **뒤**에 놓는 것이
 *   바로 이 이유입니다 — 메모리 갱신이 프롬프트 캐시를 무효화하지 않게 하려는 의도적 배치.
 *   미들웨어 순서가 곧 성능 설계인 사례입니다.
 */
function makeUsageSpy(label: string) {
  return createMiddleware({
    name: "UsageSpyMiddleware",
    afterModel: async (state) => {
      const u = (state.messages.at(-1) as any)?.usage_metadata;
      if (u) {
        console.log(
          `  [${label}] 입력=${u.input_tokens} ` +
            `캐시생성=${u.input_token_details?.cache_creation ?? 0} ` +
            `캐시읽기=${u.input_token_details?.cache_read ?? 0}`,
        );
      }
      return undefined;
    },
  });
}

async function sol8() {
  console.log("\n===== [정답 8] =====");

  // (a) 정상 — 캐시 적중
  console.log("\n(a) 캐시 정상:");
  const good = await createDeepAgent({
    model: MODEL,
    tools: [saveNote],
    systemPrompt: "당신은 메모 도우미입니다.",
    middleware: [makeUsageSpy("정상")],
  });
  const r1 = await good.invoke({ messages: [{ role: "user", content: "안녕" }] });
  await good.invoke({ messages: [...r1.messages, { role: "user", content: "반가워" }] });

  // (b) 캐시 파괴 — 매 요청 변하는 타임스탬프를 프롬프트에 주입
  console.log("\n(b) 시각 주입으로 캐시 파괴:");
  const cacheBuster = createMiddleware({
    name: "TimestampMiddleware",
    wrapModelCall: async (request, handler) =>
      handler({
        ...request,
        systemMessage: request.systemMessage.concat(
          `\n현재 시각: ${new Date().toISOString()}`, // ← 매 요청 달라진다
        ),
      }),
  });

  const bad = await createDeepAgent({
    model: MODEL,
    tools: [saveNote],
    systemPrompt: "당신은 메모 도우미입니다.",
    middleware: [cacheBuster, makeUsageSpy("파괴")],
  });
  const r2 = await bad.invoke({ messages: [{ role: "user", content: "안녕" }] });
  await bad.invoke({ messages: [...r2.messages, { role: "user", content: "반가워" }] });

  console.log("\n→ (b) 는 2회차에도 캐시읽기가 0입니다. 접두사가 매번 달라졌기 때문입니다.");
}

async function main() {
  await sol1();
  await sol2();
  await sol3();
  await sol4();
  await sol5();
  await sol6();
  await sol7();
  await sol8();
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});