#Step 09 — HITL과 권한 제어

import { createDeepAgent, StateBackend } from "deepagents";
import { MemorySaver } from "@langchain/langgraph";

const agent = await createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  backend: new StateBackend(),
  checkpointer: new MemorySaver(),
  systemPrompt: "너는 파일 관리 도우미다. 요청받은 파일 작업을 수행해라.",
});

const result = await agent.invoke(
  { messages: [{ role: "user", content: "/notes/hello.txt 에 '안녕'이라고 써줘." }] },
  { configurable: { thread_id: "9-1" } },
);

console.log("__interrupt__:", result.__interrupt__);
console.log("파일 목록:", Object.keys(result.files ?? {}));

interruptOn?: Record<string, boolean | InterruptOnConfig>

interface InterruptOnConfig {
  allowedDecisions: ("approve" | "edit" | "reject")[];  // 필수
  description?: string | ((toolCall, state, runtime) => string | Promise<string>);
  argsSchema?: Record<string, any>;   // edit 을 허용할 때 인자 JSON 스키마
  when?: (request) => boolean | Promise<boolean>;  // true 면 멈춘다
}

const agent = await createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  backend: new StateBackend(),
  checkpointer: new MemorySaver(),   // ← 없으면 아무 일도 안 일어납니다
  interruptOn: {
    // (a) 가장 단순한 형태
    write_file: true,

    // (b) 허용 결정을 좁힌다 — edit 을 빼면 사람이 인자를 못 고친다
    edit_file: {
      allowedDecisions: ["approve", "reject"],
      description: "⚠️ 파일을 수정하려 합니다. 내용을 확인하세요.",
    },

    // (c) description 을 함수로 — 툴 호출 인자를 보고 문구를 만든다
    execute: {
      allowedDecisions: ["approve", "reject"],
      description: (toolCall) =>
        `⛔ 셸 명령 실행 요청\n명령: ${JSON.stringify(toolCall.args, null, 2)}`,
    },

    // (d) 읽기 도구는 자동 승인 — 명시적으로 false
    read_file: false,
    ls: false,
    grep: false,
  },
});

import { Command, MemorySaver } from "@langchain/langgraph";
import type { HITLRequest, HITLResponse, Interrupt } from "langchain";

const agent = await createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  backend: new StateBackend(),
  checkpointer: new MemorySaver(),   // 필수
  interruptOn: { write_file: true },
});

// thread_id 는 재개할 때 같은 값을 써야 합니다. 이게 "재개 커서" 입니다.
const config = { configurable: { thread_id: "9-3" } };

// (1) 최초 호출 → interrupt 발생
const first = await agent.invoke(
  { messages: [{ role: "user", content: "/report.md 에 '분기 매출 요약'이라고 써줘." }] },
  config,
);

// (2) __interrupt__ 읽기 — value 는 HITLRequest 타입
const req = first.__interrupt__![0] as Interrupt<HITLRequest>;
console.log(JSON.stringify(req.value, null, 2));

// (3) Command 로 재개
const resume: HITLResponse = { decisions: [{ type: "approve" }] };
const second = await agent.invoke(new Command({ resume }), config);

declare const DecisionType: z.ZodEnum<["approve", "edit", "reject"]>;

// (a) approve — 원래 인자 그대로 실행
{ type: "approve" }

// (b) edit — 인자를 바꿔서 실행
{
  type: "edit",
  editedAction: { name: "write_file", args: { file_path: "/safe/draft.txt", content: "..." } }
}

// (c) reject — 실행하지 않고 message 를 모델에게 피드백
{ type: "reject", message: "루트 경로에는 파일을 만들 수 없습니다." }

const req = r1.__interrupt__![0] as Interrupt<HITLRequest>;
const original = req.value.actionRequests[0];

const resume: HITLResponse = {
  decisions: [
    {
      type: "edit",
      editedAction: {
        name: original.name,
        args: { ...original.args, file_path: "/safe/draft.txt" },  // ← 스프레드가 핵심
      },
    },
  ],
};

const resume: HITLResponse = {
  decisions: [{ type: "reject", message: "루트에는 못 씁니다. /workspace/ 아래로만 쓰세요." }],
};
const r2 = await agent.invoke(new Command({ resume }), config);

console.log("또 interrupt?", Boolean(r2.__interrupt__));   // true 일 수 있습니다

interface FilesystemPermission {
  operations: readonly ("read" | "write")[];
  paths: string[];             // 절대 glob. `/` 로 시작해야 하고 `..` `~` 불가
  mode?: "allow" | "deny";     // 기본값 "allow"
}

const agent = await createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  backend: new StateBackend(),
  checkpointer: new MemorySaver(),
  permissions: [
    // 1) /workspace 아래는 읽기·쓰기 허용
    { operations: ["read", "write"], paths: ["/workspace/**"], mode: "allow" },
    // 2) /secrets 아래는 읽기조차 금지
    { operations: ["read", "write"], paths: ["/secrets/**"], mode: "deny" },
    // 3) 그 외 전부 금지 — 이 "마지막 빗장"이 반드시 필요합니다
    { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
  ],
});

const agent = await createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  backend: new StateBackend(),
  checkpointer: new MemorySaver(),
  permissions: [
    { operations: ["read", "write"], paths: ["/workspace/**"], mode: "allow" },
    { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
  ],
  interruptOn: { write_file: true },
  subagents: [
    {
      name: "auditor",
      description: "코드를 읽고 문제점만 보고한다. 절대 파일을 수정하지 않는다.",
      systemPrompt: "너는 감사자다. 읽기만 하고 발견한 문제를 목록으로 보고해라.",
      // 부모 규칙을 통째로 교체 — 이 배열만으로 완결적이어야 합니다
      permissions: [
        { operations: ["write"], paths: ["/**"], mode: "deny" },
        { operations: ["read"], paths: ["/workspace/**"], mode: "allow" },
        { operations: ["read"], paths: ["/**"], mode: "deny" },
      ],
      // 쓰기가 애초에 불가능하니 승인 게이트가 불필요 → 감사자는 안 멈추고 끝까지 돈다
      interruptOn: {},
    },
    {
      name: "writer",
      description: "감사 결과를 바탕으로 파일을 실제로 수정한다.",
      systemPrompt: "너는 수정자다. 감사 결과를 반영해 파일을 고쳐라.",
      // permissions 생략 → 부모 규칙 상속
      interruptOn: {
        write_file: { allowedDecisions: ["approve", "edit", "reject"] },
        edit_file: { allowedDecisions: ["approve", "edit", "reject"] },
      },
    },
  ],
});

const deployTool = tool(
  async ({ env }) => `${env} 에 배포했습니다.`,
  {
    name: "deploy",
    description: "지정한 환경에 애플리케이션을 배포한다.",
    schema: z.object({ env: z.enum(["staging", "production"]) }),
  },
);

const agent = await createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  backend: new StateBackend(),
  checkpointer: new MemorySaver(),
  tools: [deployTool],

  // 등급 1(read): 정적 규칙으로 범위만 제한, 승인 없음
  permissions: [
    { operations: ["read"], paths: ["/workspace/**"], mode: "allow" },
    { operations: ["write"], paths: ["/workspace/**"], mode: "allow" },
    { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
  ],

  interruptOn: {
    // 등급 1: 자동 승인
    read_file: false, ls: false, grep: false, glob: false,

    // 등급 2(write): 승인 필요, 인자 수정 허용
    write_file: {
      allowedDecisions: ["approve", "edit", "reject"],
      description: (toolCall) => `📝 파일 쓰기: ${toolCall.args.file_path}`,
    },
    edit_file: { allowedDecisions: ["approve", "edit", "reject"] },

    // 등급 3(execute): 승인 필요 + edit 금지 + when 으로 production 만 거른다
    deploy: {
      allowedDecisions: ["approve", "reject"],
      description: (toolCall) => `🚨 PRODUCTION 배포 요청 (env=${toolCall.args.env})`,
      when: (request) => request.toolCall.args.env === "production",
    },
  },
});

import * as readline from "node:readline/promises";

/** __interrupt__ 를 사람에게 보여주고 y/n/e 를 받아 HITLResponse 로 바꾼다. */
async function askHuman(req: Interrupt<HITLRequest>): Promise<HITLResponse> {
  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
  const decisions: HITLResponse["decisions"] = [];

  try {
    for (const action of req.value.actionRequests) {
      // reviewConfigs 는 actionName 으로 찾습니다 (인덱스 대응이 아닙니다)
      const review = req.value.reviewConfigs.find((c) => c.actionName === action.name);
      const allowed = review?.allowedDecisions ?? ["approve", "reject"];

      console.log(`\n도구: ${action.name}`);
      if (action.description) console.log(action.description);
      console.log("인자:\n" + JSON.stringify(action.args, null, 2));
      console.log(`허용된 결정: ${allowed.join(" / ")}`);

      const answer = (await rl.question("승인? [y / n / e] ")).trim().toLowerCase();

      if (answer === "y" && allowed.includes("approve")) {
        decisions.push({ type: "approve" });
      } else if (answer === "e" && allowed.includes("edit")) {
        const raw = await rl.question("새 args (JSON): ");
        decisions.push({ type: "edit", editedAction: { name: action.name, args: JSON.parse(raw) } });
      } else {
        const why = await rl.question("거절 사유 (모델에게 전달됩니다): ");
        decisions.push({ type: "reject", message: why || "사용자가 거절했습니다." });
      }
    }
  } finally {
    rl.close();
  }

  return { decisions };
}

let result = await agent.invoke(
  { messages: [{ role: "user", content: "/workspace/README.md 를 만들고 '# 프로젝트' 를 넣어줘." }] },
  config,
);

// interrupt 가 없어질 때까지 승인 루프를 돈다
while (result.__interrupt__) {
  const req = result.__interrupt__[0] as Interrupt<HITLRequest>;
  const resume = await askHuman(req);
  result = await agent.invoke(new Command({ resume }), config);
}

/**
 * Step 09 — HITL과 권한 제어
 * 실행: npx tsx docs/reference/deepagent/step-09-hitl-permissions/practice.ts
 *
 * 본문 9-1 ~ 9-8 의 예제를 순서대로 담았습니다.
 * 검증 버전: deepagents 1.11.0 / langchain 1.5.3 / @langchain/langgraph 1.4.8
 */
import "dotenv/config";
import { createDeepAgent, StateBackend } from "deepagents";
import { Command, MemorySaver } from "@langchain/langgraph";
import { tool } from "langchain";
import type { HITLRequest, HITLResponse, Interrupt } from "langchain";
import * as z from "zod";
import * as readline from "node:readline/promises";

const MODEL = "anthropic:claude-sonnet-4-6";
// OpenAI 대안: const MODEL = "openai:gpt-5.5";

/* ===== [9-1] Deep Agent 는 왜 더 위험한가 ===== */
// 일반 에이전트는 "말"만 하지만 Deep Agent 는 파일을 쓰고 서브에이전트를 스폰합니다.
// 아래는 아무 통제 없이 write_file 을 쓰는 에이전트 — 실행하면 그냥 써버립니다.

async function step9_1() {
  console.log("\n===== [9-1] 통제 없는 Deep Agent =====");

  const agent = await createDeepAgent({
    model: MODEL,
    backend: new StateBackend(), // 가상 FS 라서 실습은 안전합니다
    checkpointer: new MemorySaver(),
    systemPrompt: "너는 파일 관리 도우미다. 요청받은 파일 작업을 수행해라.",
  });

  const result = await agent.invoke(
    { messages: [{ role: "user", content: "/notes/hello.txt 에 '안녕'이라고 써줘." }] },
    { configurable: { thread_id: "9-1" } },
  );

  // 승인 절차가 하나도 없었습니다. __interrupt__ 는 undefined 입니다.
  console.log("__interrupt__:", result.__interrupt__);
  console.log("파일 목록:", Object.keys(result.files ?? {}));
}

/* ===== [9-2] interruptOn — 어떤 도구에 승인을 걸 것인가 ===== */
// interruptOn: Record<string, boolean | InterruptOnConfig>
//   true                 -> 승인 대기 (approve/edit/reject 모두 허용)
//   false                -> 자동 승인 (= 키를 안 적은 것과 같음)
//   InterruptOnConfig    -> 허용 결정을 명시적으로 지정

async function step9_2() {
  console.log("\n===== [9-2] interruptOn 설정 형식 =====");

  const agent = await createDeepAgent({
    model: MODEL,
    backend: new StateBackend(),
    checkpointer: new MemorySaver(), // ← 없으면 interrupt 가 동작하지 않습니다
    interruptOn: {
      // (a) 불리언 true — 가장 단순한 형태
      write_file: true,

      // (b) InterruptOnConfig — 허용 결정을 좁힌다
      edit_file: {
        allowedDecisions: ["approve", "reject"], // edit 은 뺐다 = 인자 수정 불가
        description: "⚠️ 파일을 수정하려 합니다. 내용을 확인하세요.",
      },

      // (c) description 을 함수로 — 툴 호출 인자를 보고 문구를 만든다
      execute: {
        allowedDecisions: ["approve", "reject"],
        description: (toolCall) =>
          `⛔ 셸 명령 실행 요청\n명령: ${JSON.stringify(toolCall.args, null, 2)}`,
      },

      // (d) 읽기 도구는 자동 승인 — 명시적으로 false
      read_file: false,
      ls: false,
      grep: false,
    },
  });

  console.log("에이전트 생성됨. interruptOn 이 걸린 도구: write_file, edit_file, execute");
  return agent;
}

/* ===== [9-3] 승인 흐름 — interrupt → __interrupt__ → Command resume ===== */

async function step9_3() {
  console.log("\n===== [9-3] 승인 흐름 3단계 =====");

  const agent = await createDeepAgent({
    model: MODEL,
    backend: new StateBackend(),
    checkpointer: new MemorySaver(), // 필수
    interruptOn: { write_file: true },
  });

  // thread_id 는 재개할 때 같은 값을 써야 합니다. 이게 "재개 커서" 입니다.
  const config = { configurable: { thread_id: "9-3" } };

  // (1) 최초 호출 → interrupt 발생
  const first = await agent.invoke(
    { messages: [{ role: "user", content: "/report.md 에 '분기 매출 요약'이라고 써줘." }] },
    config,
  );

  if (!first.__interrupt__) {
    console.log("interrupt 가 발생하지 않았습니다 (모델이 도구를 안 불렀을 수 있음)");
    return;
  }

  // (2) __interrupt__ 읽기 — value 는 HITLRequest 타입
  const req = first.__interrupt__[0] as Interrupt<HITLRequest>;
  console.log("actionRequests:", JSON.stringify(req.value.actionRequests, null, 2));
  console.log("reviewConfigs:", JSON.stringify(req.value.reviewConfigs, null, 2));

  // (3) Command 로 재개 — decisions 는 actionRequests 와 같은 순서/같은 개수
  const resume: HITLResponse = { decisions: [{ type: "approve" }] };
  const second = await agent.invoke(new Command({ resume }), config);

  console.log("재개 후 파일 목록:", Object.keys(second.files ?? {}));
}

/* ===== [9-4] 승인 액션 — approve / edit / reject ===== */
// langchain 1.5.3 의 DecisionType 은 정확히 세 가지입니다: "approve" | "edit" | "reject"

async function step9_4() {
  console.log("\n===== [9-4] 세 가지 승인 액션 =====");

  const makeAgent = async () =>
    createDeepAgent({
      model: MODEL,
      backend: new StateBackend(),
      checkpointer: new MemorySaver(),
      interruptOn: {
        write_file: { allowedDecisions: ["approve", "edit", "reject"] },
      },
    });

  const prompt = "/draft.txt 에 '초안입니다'라고 써줘.";

  // --- (a) approve: 원래 인자 그대로 실행
  {
    const agent = await makeAgent();
    const config = { configurable: { thread_id: "9-4-approve" } };
    const r1 = await agent.invoke({ messages: [{ role: "user", content: prompt }] }, config);
    if (r1.__interrupt__) {
      const resume: HITLResponse = { decisions: [{ type: "approve" }] };
      const r2 = await agent.invoke(new Command({ resume }), config);
      console.log("[approve] 파일:", Object.keys(r2.files ?? {}));
    }
  }

  // --- (b) edit: 인자를 바꿔서 실행. editedAction 에 name 과 args 를 "전부" 다시 준다.
  {
    const agent = await makeAgent();
    const config = { configurable: { thread_id: "9-4-edit" } };
    const r1 = await agent.invoke({ messages: [{ role: "user", content: prompt }] }, config);
    if (r1.__interrupt__) {
      const req = r1.__interrupt__[0] as Interrupt<HITLRequest>;
      const original = req.value.actionRequests[0];
      if (!original) return;
      const resume: HITLResponse = {
        decisions: [
          {
            type: "edit",
            editedAction: {
              name: original.name, // 도구 이름도 바꿀 수 있지만 보통 그대로 둡니다
              args: { ...original.args, file_path: "/safe/draft.txt" }, // 경로만 교정
            },
          },
        ],
      };
      const r2 = await agent.invoke(new Command({ resume }), config);
      console.log("[edit] 파일:", Object.keys(r2.files ?? {}));
    }
  }

  // --- (c) reject: 실행하지 않고 message 를 모델에게 피드백으로 돌려준다
  {
    const agent = await makeAgent();
    const config = { configurable: { thread_id: "9-4-reject" } };
    const r1 = await agent.invoke({ messages: [{ role: "user", content: prompt }] }, config);
    if (r1.__interrupt__) {
      const resume: HITLResponse = {
        decisions: [
          {
            type: "reject",
            message: "루트 경로에는 파일을 만들 수 없습니다. /workspace/ 아래로만 쓰세요.",
          },
        ],
      };
      const r2 = await agent.invoke(new Command({ resume }), config);
      // reject 는 "거절 후 모델이 다시 시도" 하므로 또 interrupt 가 날 수 있습니다.
      console.log("[reject] 또 interrupt?", Boolean(r2.__interrupt__));
    }
  }
}

/* ===== [9-5] permissions — 백엔드 레벨 정적 접근 제어 ===== */
// FilesystemPermission = { operations: ("read"|"write")[]; paths: string[]; mode?: "allow"|"deny" }
// 규칙은 선언 순서대로 평가되고 first-match-wins. 어디에도 안 걸리면 기본 allow.

async function step9_5() {
  console.log("\n===== [9-5] permissions 정적 규칙 =====");

  const agent = await createDeepAgent({
    model: MODEL,
    backend: new StateBackend(),
    checkpointer: new MemorySaver(),
    permissions: [
      // 1) /workspace 아래는 읽기·쓰기 허용
      { operations: ["read", "write"], paths: ["/workspace/**"], mode: "allow" },
      // 2) /secrets 아래는 읽기조차 금지
      { operations: ["read", "write"], paths: ["/secrets/**"], mode: "deny" },
      // 3) 그 외 전부 금지 (기본이 allow 이므로 이 "마지막 빗장"이 반드시 필요)
      { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
    ],
  });

  const result = await agent.invoke(
    { messages: [{ role: "user", content: "/secrets/keys.env 를 읽어서 내용을 알려줘." }] },
    { configurable: { thread_id: "9-5" } },
  );

  // 도구가 에러 문자열을 ToolMessage 로 돌려주고, 모델은 그걸 보고 사용자에게 설명합니다.
  const last = result.messages.at(-1);
  console.log("모델 최종 답변:", last?.text);
}

/* ===== [9-6] 서브에이전트별 interruptOn / permissions ===== */
// permissions: 생략 = 부모 상속 / 명시 = 부모 규칙을 통째로 교체 / [] = 무제한

async function step9_6() {
  console.log("\n===== [9-6] 서브에이전트별 정책 =====");

  const agent = await createDeepAgent({
    model: MODEL,
    backend: new StateBackend(),
    checkpointer: new MemorySaver(),
    permissions: [
      { operations: ["read", "write"], paths: ["/workspace/**"], mode: "allow" },
      { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
    ],
    interruptOn: { write_file: true },
    subagents: [
      {
        name: "auditor",
        description: "코드를 읽고 문제점만 보고한다. 절대 파일을 수정하지 않는다.",
        systemPrompt: "너는 감사자다. 읽기만 하고 발견한 문제를 목록으로 보고해라.",
        // 부모 규칙을 통째로 교체 — 쓰기는 전면 금지, 읽기는 /workspace 만
        permissions: [
          { operations: ["write"], paths: ["/**"], mode: "deny" },
          { operations: ["read"], paths: ["/workspace/**"], mode: "allow" },
          { operations: ["read"], paths: ["/**"], mode: "deny" },
        ],
        // 쓰기가 애초에 불가능하므로 승인 게이트가 필요 없다 → 감사자는 멈추지 않고 끝까지 돈다
        interruptOn: {},
      },
      {
        name: "writer",
        description: "감사 결과를 바탕으로 파일을 실제로 수정한다.",
        systemPrompt: "너는 수정자다. 감사 결과를 반영해 파일을 고쳐라.",
        // permissions 생략 → 부모 규칙 상속
        interruptOn: {
          write_file: { allowedDecisions: ["approve", "edit", "reject"] },
          edit_file: { allowedDecisions: ["approve", "edit", "reject"] },
        },
      },
    ],
  });

  console.log("auditor(읽기 전용, 승인 없음) / writer(부모 권한 상속, 승인 필수) 구성 완료");
  return agent;
}

/* ===== [9-7] 위험 등급별 정책 설계 ===== */
// read = 자유 / write = 승인 / execute = 금지(또는 샌드박스)

async function step9_7() {
  console.log("\n===== [9-7] 위험 등급별 정책 =====");

  const deployTool = tool(
    async ({ env }) => `${env} 에 배포했습니다.`,
    {
      name: "deploy",
      description: "지정한 환경에 애플리케이션을 배포한다.",
      schema: z.object({ env: z.enum(["staging", "production"]) }),
    },
  );

  const agent = await createDeepAgent({
    model: MODEL,
    backend: new StateBackend(),
    checkpointer: new MemorySaver(),
    tools: [deployTool],

    // 등급 1(read): 정적 규칙으로 범위만 제한, 승인 없음
    permissions: [
      { operations: ["read"], paths: ["/workspace/**"], mode: "allow" },
      { operations: ["write"], paths: ["/workspace/**"], mode: "allow" },
      { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
    ],

    interruptOn: {
      // 등급 1: 자동 승인
      read_file: false,
      ls: false,
      grep: false,
      glob: false,

      // 등급 2(write): 승인 필요, 인자 수정 허용
      write_file: {
        allowedDecisions: ["approve", "edit", "reject"],
        description: (toolCall) => `📝 파일 쓰기: ${toolCall.args.file_path}`,
      },
      edit_file: { allowedDecisions: ["approve", "edit", "reject"] },

      // 등급 3(execute): 승인 필요 + edit 금지. 게다가 when 으로 production 만 걸러낸다.
      deploy: {
        allowedDecisions: ["approve", "reject"],
        description: (toolCall) => `🚨 PRODUCTION 배포 요청 (env=${toolCall.args.env})`,
        // staging 배포는 자동 승인, production 만 사람을 부른다
        when: (request) => request.toolCall.args.env === "production",
      },
    },
  });

  console.log("read=자유 / write=승인 / deploy=production 만 승인 구성 완료");
  return agent;
}

/* ===== [9-8] 실전: 승인 게이트 달린 파일 편집 에이전트 (CLI) ===== */

/** __interrupt__ 를 사람에게 보여주고 y/n/e 를 받아 HITLResponse 로 바꾼다. */
async function askHuman(req: Interrupt<HITLRequest>): Promise<HITLResponse> {
  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
  const decisions: HITLResponse["decisions"] = [];

  try {
    // for...of 로 도는 이유: 인덱스 접근은 tsconfig 의 noUncheckedIndexedAccess 때문에
    // 매번 undefined 체크를 요구합니다. 순서만 지키면 되므로 for...of 가 깔끔합니다.
    for (const action of req.value.actionRequests) {
      // reviewConfigs 는 actionName 으로 찾습니다 (인덱스 대응이 아닙니다)
      const review = req.value.reviewConfigs.find((c) => c.actionName === action.name);
      const allowed = review?.allowedDecisions ?? ["approve", "reject"];

      console.log("\n" + "─".repeat(60));
      console.log(`도구: ${action.name}`);
      if (action.description) console.log(action.description);
      console.log("인자:");
      console.log(JSON.stringify(action.args, null, 2));
      console.log(`허용된 결정: ${allowed.join(" / ")}`);
      console.log("─".repeat(60));

      const answer = (await rl.question("승인? [y=approve / n=reject / e=edit] ")).trim().toLowerCase();

      if (answer === "y" && allowed.includes("approve")) {
        decisions.push({ type: "approve" });
      } else if (answer === "e" && allowed.includes("edit")) {
        const raw = await rl.question("새 args (JSON): ");
        decisions.push({
          type: "edit",
          editedAction: { name: action.name, args: JSON.parse(raw) },
        });
      } else {
        const why = await rl.question("거절 사유 (모델에게 전달됩니다): ");
        decisions.push({ type: "reject", message: why || "사용자가 거절했습니다." });
      }
    }
  } finally {
    rl.close();
  }

  return { decisions };
}

async function step9_8() {
  console.log("\n===== [9-8] 승인 게이트 달린 파일 편집 에이전트 =====");

  const agent = await createDeepAgent({
    model: MODEL,
    backend: new StateBackend(),
    checkpointer: new MemorySaver(),
    systemPrompt:
      "너는 파일 편집 도우미다. 파일을 쓰기 전에 항상 먼저 읽어서 현재 내용을 확인해라.",
    permissions: [
      { operations: ["read", "write"], paths: ["/workspace/**"], mode: "allow" },
      { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
    ],
    interruptOn: {
      write_file: { allowedDecisions: ["approve", "edit", "reject"] },
      edit_file: { allowedDecisions: ["approve", "edit", "reject"] },
    },
  });

  const config = { configurable: { thread_id: "9-8" } };

  let result = await agent.invoke(
    {
      messages: [
        {
          role: "user",
          content: "/workspace/README.md 를 만들고 '# 프로젝트' 라는 제목을 넣어줘.",
        },
      ],
    },
    config,
  );

  // interrupt 가 없어질 때까지 승인 루프를 돈다.
  // 한 번의 실행에서 여러 번 interrupt 가 날 수 있습니다 (도구 호출마다).
  while (result.__interrupt__) {
    const req = result.__interrupt__[0] as Interrupt<HITLRequest>;
    const resume = await askHuman(req);
    result = await agent.invoke(new Command({ resume }), config);
  }

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

/* ===== 실행 ===== */
async function main() {
  await step9_1();
  await step9_2();
  await step9_3();
  await step9_4();
  await step9_5();
  await step9_6();
  await step9_7();
  await step9_8(); // ← stdin 입력이 필요합니다
}

main().catch(console.error);

/**
 * Step 09 — HITL과 권한 제어 · 연습문제
 * 실행: npx tsx docs/reference/deepagent/step-09-hitl-permissions/exercise.ts
 *
 * 각 [문제 N] 아래 빈 곳을 직접 채우세요.
 * 정답은 solution.ts 에 있습니다. 먼저 스스로 풀어보세요.
 */
import "dotenv/config";
import { createDeepAgent, StateBackend } from "deepagents";
import { Command, MemorySaver } from "@langchain/langgraph";
import { tool } from "langchain";
import type { HITLRequest, HITLResponse, Interrupt } from "langchain";
import * as z from "zod";

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

/* ===== [문제 1] 승인 게이트 켜기 =====
 * write_file 에만 승인을 걸고 read_file / ls 는 자동 승인되는 에이전트를 만드세요.
 * 힌트: interruptOn 과 checkpointer 를 함께 줘야 합니다.
 *       checkpointer 를 빼면 어떻게 되는지도 직접 확인해 보세요.
 */
async function ex1() {
  // 여기에 작성
}

/* ===== [문제 2] __interrupt__ 읽기 =====
 * 문제 1의 에이전트에게 "/notes/todo.md 에 '할 일'이라고 써줘" 를 시키고,
 * interrupt 가 발생하면 actionRequests 의 도구 이름과 인자를 출력하세요.
 * 그리고 reviewConfigs 에서 그 도구의 allowedDecisions 를 찾아 출력하세요.
 * 힌트: reviewConfigs 는 actionName 으로 찾습니다.
 */
async function ex2() {
  // 여기에 작성
}

/* ===== [문제 3] edit 결정으로 경로 교정 =====
 * 문제 2에서 받은 interrupt 를 approve 하지 말고 edit 으로 재개하세요.
 * 모델이 요청한 file_path 가 무엇이든 "/workspace/todo.md" 로 바꿔서 실행되게 하세요.
 * 힌트: editedAction 에는 name 과 args 를 "전부" 다시 줘야 합니다.
 *       원본 args 를 스프레드한 뒤 file_path 만 덮어쓰세요.
 */
async function ex3() {
  // 여기에 작성
}

/* ===== [문제 4] reject 와 피드백 =====
 * write_file 을 reject 하되, message 에 "쓰기는 금지입니다. 대신 내용을 채팅으로 알려주세요."
 * 를 넣어 모델에게 피드백하세요. 재개 후 모델이 뭐라고 응답하는지 확인하세요.
 * 재개 결과에 또 __interrupt__ 가 있는지도 확인하세요 (모델이 재시도할 수 있습니다).
 */
async function ex4() {
  // 여기에 작성
}

/* ===== [문제 5] permissions 로 샌드박싱 =====
 * 다음을 만족하는 permissions 배열을 작성하세요.
 *   - /workspace 아래: 읽기·쓰기 모두 허용
 *   - /config 아래: 읽기만 허용, 쓰기 금지
 *   - 그 외 모든 경로: 읽기·쓰기 모두 금지
 * 힌트: 규칙은 first-match-wins 이고, 아무 규칙에도 안 걸리면 기본이 allow 입니다.
 *       규칙 순서가 중요합니다. 그리고 마지막 "빗장" 규칙을 잊지 마세요.
 */
async function ex5() {
  // 여기에 작성
}

/* ===== [문제 6] when 으로 조건부 승인 =====
 * 아래 transferMoney 도구에 승인을 걸되,
 * 100000원 이하는 자동 승인되고 그보다 크면 사람을 부르게 하세요.
 * 힌트: InterruptOnConfig 의 when 은 true 를 반환하면 "멈춘다" 입니다.
 */
const transferMoney = tool(
  async ({ to, amount }) => `${to} 에게 ${amount}원을 송금했습니다.`,
  {
    name: "transfer_money",
    description: "지정한 상대에게 돈을 송금한다.",
    schema: z.object({ to: z.string(), amount: z.number() }),
  },
);

async function ex6() {
  // 여기에 작성
}

/* ===== [문제 7] 읽기 전용 서브에이전트 =====
 * "reviewer" 서브에이전트를 정의하세요.
 *   - 어떤 경로에도 쓰기를 할 수 없어야 합니다
 *   - /workspace 아래는 읽을 수 있어야 합니다
 *   - 부모의 permissions 를 상속하면 안 됩니다 (통째로 교체)
 * 부모 에이전트는 /workspace 읽기·쓰기가 모두 허용된 상태로 두세요.
 * 힌트: permissions 를 생략하면 상속, 명시하면 교체, [] 는 무제한입니다.
 */
async function ex7() {
  // 여기에 작성
}

/* ===== [문제 8] 승인 루프 =====
 * 에이전트를 실행하고, __interrupt__ 가 사라질 때까지 반복하며
 * 모든 요청을 자동으로 approve 하는 루프를 작성하세요.
 * 단, 무한 루프를 막기 위해 최대 5회까지만 재개하고 그 이상이면 경고를 출력하세요.
 * 힌트: while (result.__interrupt__) 형태이되 카운터를 두세요.
 *       decisions 배열의 길이는 actionRequests 길이와 같아야 합니다.
 */
async function ex8() {
  // 여기에 작성
}

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

main().catch(console.error);

/**
 * Step 09 — HITL과 권한 제어 · 정답과 해설
 * 실행: npx tsx docs/reference/deepagent/step-09-hitl-permissions/solution.ts
 *
 * exercise.ts 를 먼저 스스로 풀어본 뒤에 열어보세요.
 */
import "dotenv/config";
import { createDeepAgent, StateBackend } from "deepagents";
import { Command, MemorySaver } from "@langchain/langgraph";
import { tool } from "langchain";
import type { HITLRequest, HITLResponse, Interrupt } from "langchain";
import * as z from "zod";

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

/* ===== [정답 1] 승인 게이트 켜기 =====
 * 핵심은 checkpointer 입니다. interruptOn 만 주고 checkpointer 를 빼면
 * 에이전트는 "멈추지 않고 그냥 실행" 합니다. 에러도 안 납니다 — 이게 이 스텝 최대의 함정입니다.
 * interrupt 는 상태를 저장했다가 나중에 되살리는 메커니즘인데,
 * 저장할 곳(checkpointer)이 없으면 되살릴 수도 없기 때문입니다.
 *
 * read_file: false 는 사실 생략해도 같습니다 — interruptOn 에 없는 키는 자동 승인이 기본입니다.
 * 그래도 "읽기는 일부러 자유롭게 뒀다"는 의도를 코드로 남기려고 명시하는 편이 좋습니다.
 */
function makeAgent1() {
  return createDeepAgent({
    model: MODEL,
    backend: new StateBackend(),
    checkpointer: new MemorySaver(), // ← 이게 없으면 interrupt 는 무동작
    interruptOn: {
      write_file: true, // true = approve/edit/reject 모두 허용하며 멈춤
      read_file: false, // false = 자동 승인 (명시적 의도 표현)
      ls: false,
    },
  });
}

async function sol1() {
  console.log("\n===== [정답 1] =====");
  const agent = await makeAgent1();
  const result = await agent.invoke(
    { messages: [{ role: "user", content: "/notes/todo.md 에 '할 일'이라고 써줘." }] },
    { configurable: { thread_id: "sol-1" } },
  );
  console.log("interrupt 발생?", Boolean(result.__interrupt__));
}

/* ===== [정답 2] __interrupt__ 읽기 =====
 * __interrupt__ 는 배열입니다. HITL 미들웨어는 한 턴의 승인 요청을
 * "하나의 interrupt" 로 묶으므로 보통 [0] 만 보면 됩니다.
 * 대신 그 안의 actionRequests 가 배열이라 도구 호출이 여러 개일 수 있습니다.
 *
 * 함정: reviewConfigs 를 actionRequests 와 같은 인덱스로 짝지으면 안 됩니다.
 * reviewConfigs 는 "도구별" 정책이라 같은 도구를 두 번 부르면 항목이 하나뿐일 수 있습니다.
 * 반드시 actionName 으로 찾으세요.
 */
async function sol2() {
  console.log("\n===== [정답 2] =====");
  const agent = await makeAgent1();
  const result = await agent.invoke(
    { messages: [{ role: "user", content: "/notes/todo.md 에 '할 일'이라고 써줘." }] },
    { configurable: { thread_id: "sol-2" } },
  );

  if (!result.__interrupt__) {
    console.log("모델이 도구를 부르지 않았습니다.");
    return;
  }

  const req = result.__interrupt__[0] as Interrupt<HITLRequest>;
  for (const action of req.value.actionRequests) {
    console.log("도구 이름:", action.name);
    console.log("인자:", JSON.stringify(action.args, null, 2));
    // 인덱스가 아니라 actionName 으로 찾는 것이 포인트
    const review = req.value.reviewConfigs.find((c) => c.actionName === action.name);
    console.log("허용된 결정:", review?.allowedDecisions);
  }
}

/* ===== [정답 3] edit 결정으로 경로 교정 =====
 * editedAction 은 원본을 "부분 수정" 하는 게 아니라 "통째로 교체" 합니다.
 * args 에 file_path 만 넣으면 content 가 사라져서 도구 호출이 실패합니다.
 * 그래서 원본 args 를 스프레드한 뒤 바꿀 키만 덮어써야 합니다.
 *
 * name 도 바꿀 수 있지만(다른 도구로 갈아끼우기), 보통은 원본 이름을 그대로 씁니다.
 */
async function sol3() {
  console.log("\n===== [정답 3] =====");
  const agent = await makeAgent1();
  const config = { configurable: { thread_id: "sol-3" } };

  const r1 = await agent.invoke(
    { messages: [{ role: "user", content: "/notes/todo.md 에 '할 일'이라고 써줘." }] },
    config,
  );
  if (!r1.__interrupt__) return;

  const req = r1.__interrupt__[0] as Interrupt<HITLRequest>;
  const original = req.value.actionRequests[0];
  if (!original) return;

  const resume: HITLResponse = {
    decisions: [
      {
        type: "edit",
        editedAction: {
          name: original.name,
          // ...original.args 가 핵심. content 를 잃지 않으려면 반드시 펼쳐야 합니다.
          args: { ...original.args, file_path: "/workspace/todo.md" },
        },
      },
    ],
  };

  const r2 = await agent.invoke(new Command({ resume }), config);
  // /notes/todo.md 가 아니라 /workspace/todo.md 가 만들어졌는지 확인
  console.log("파일 목록:", Object.keys(r2.files ?? {}));
}

/* ===== [정답 4] reject 와 피드백 =====
 * reject 는 "도구를 실행하지 않고, message 를 도구 결과인 것처럼 모델에게 돌려주는 것" 입니다.
 * 모델 입장에서는 도구가 실패 메시지를 반환한 것처럼 보이므로, 그걸 읽고 다음 행동을 정합니다.
 *
 * 함정: reject 했다고 대화가 끝나지 않습니다. 모델은 다른 경로로 재시도할 수 있고,
 * 그러면 __interrupt__ 가 또 발생합니다. 그래서 실전에서는 정답 8처럼 루프가 필요합니다.
 * message 를 비워두면 모델이 왜 거절당했는지 몰라서 같은 시도를 반복합니다 — 반드시 이유를 적으세요.
 */
async function sol4() {
  console.log("\n===== [정답 4] =====");
  const agent = await makeAgent1();
  const config = { configurable: { thread_id: "sol-4" } };

  const r1 = await agent.invoke(
    { messages: [{ role: "user", content: "/notes/todo.md 에 '할 일'이라고 써줘." }] },
    config,
  );
  if (!r1.__interrupt__) return;

  const resume: HITLResponse = {
    decisions: [
      {
        type: "reject",
        message: "쓰기는 금지입니다. 대신 내용을 채팅으로 알려주세요.",
      },
    ],
  };

  const r2 = await agent.invoke(new Command({ resume }), config);
  console.log("모델 응답:", r2.messages.at(-1)?.text);
  console.log("또 interrupt?", Boolean(r2.__interrupt__)); // 재시도하면 true 일 수 있습니다
}

/* ===== [정답 5] permissions 로 샌드박싱 =====
 * 순서가 전부입니다. first-match-wins 이므로 좁은 규칙을 먼저, 넓은 빗장을 마지막에 둡니다.
 *
 * /config 는 "읽기 허용 + 쓰기 금지" 인데, 쓰기 금지 규칙을 따로 쓰지 않아도
 * 마지막 빗장 규칙이 잡아줍니다. 하지만 의도를 명확히 하려고 명시적으로 적었습니다.
 *
 * 마지막 { paths: ["/**"], mode: "deny" } 를 빼면 어떤 규칙에도 안 걸리는 경로가
 * 기본값 allow 로 통과합니다. "허용 목록만 적었으니 나머지는 막히겠지" 가 아닙니다 —
 * deny 기본이 아니라 allow 기본입니다. 이 빗장이 이 문제의 핵심입니다.
 */
async function sol5() {
  console.log("\n===== [정답 5] =====");

  const agent = await createDeepAgent({
    model: MODEL,
    backend: new StateBackend(),
    checkpointer: new MemorySaver(),
    permissions: [
      // 1) 가장 구체적인 허용부터
      { operations: ["read", "write"], paths: ["/workspace/**"], mode: "allow" },
      // 2) /config 는 읽기만 — 쓰기 금지를 읽기 허용보다 먼저 둬야 합니다.
      //    순서를 바꾸면 read 규칙이 먼저 매칭되지만 operations 가 달라 write 는 안 걸리고,
      //    결국 아래 빗장에 걸립니다. 그래도 의도를 코드에 남기는 편이 안전합니다.
      { operations: ["write"], paths: ["/config/**"], mode: "deny" },
      { operations: ["read"], paths: ["/config/**"], mode: "allow" },
      // 3) 마지막 빗장 — 이게 없으면 나머지 전부 allow 입니다
      { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
    ],
  });

  const result = await agent.invoke(
    { messages: [{ role: "user", content: "/config/app.json 에 설정을 써줘." }] },
    { configurable: { thread_id: "sol-5" } },
  );
  console.log("모델 응답:", result.messages.at(-1)?.text);
}

/* ===== [정답 6] when 으로 조건부 승인 =====
 * when 은 "멈출지 말지" 를 결정하는 술어입니다. true = 멈춘다, false = 자동 승인.
 * 헷갈리기 쉬우니 주의: when 은 "허용 조건" 이 아니라 "개입 조건" 입니다.
 *
 * when 이 유용한 이유는 승인 피로(approval fatigue) 때문입니다.
 * 1000원 송금까지 전부 사람을 부르면, 사람은 곧 내용을 안 읽고 y 만 누르게 됩니다.
 * 그러면 승인 게이트는 있으나 마나입니다. 정말 위험한 것만 골라서 물어야 합니다.
 *
 * 주의: when 안에서는 request.tool 이 undefined 입니다(afterModel 단계라서).
 * request.toolCall.args 만 쓰세요.
 */
const transferMoney = tool(
  async ({ to, amount }) => `${to} 에게 ${amount}원을 송금했습니다.`,
  {
    name: "transfer_money",
    description: "지정한 상대에게 돈을 송금한다.",
    schema: z.object({ to: z.string(), amount: z.number() }),
  },
);

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

  const agent = await createDeepAgent({
    model: MODEL,
    backend: new StateBackend(),
    checkpointer: new MemorySaver(),
    tools: [transferMoney],
    interruptOn: {
      transfer_money: {
        allowedDecisions: ["approve", "reject"],
        description: (toolCall) =>
          `🚨 고액 송금: ${toolCall.args.to} 에게 ${toolCall.args.amount}원`,
        // true 를 반환하면 멈춘다. 10만원 초과만 사람을 부른다.
        when: (request) => Number(request.toolCall.args.amount ?? 0) > 100000,
      },
    },
  });

  const config = { configurable: { thread_id: "sol-6" } };

  // 5만원 — 자동 승인되어 interrupt 없이 끝납니다
  const small = await agent.invoke(
    { messages: [{ role: "user", content: "김철수에게 50000원 송금해줘." }] },
    config,
  );
  console.log("5만원 → interrupt?", Boolean(small.__interrupt__)); // false 기대

  // 100만원 — 멈춥니다
  const big = await agent.invoke(
    { messages: [{ role: "user", content: "이영희에게 1000000원 송금해줘." }] },
    { configurable: { thread_id: "sol-6-big" } },
  );
  console.log("100만원 → interrupt?", Boolean(big.__interrupt__)); // true 기대
}

/* ===== [정답 7] 읽기 전용 서브에이전트 =====
 * permissions 를 명시하면 부모 규칙을 "통째로 교체" 합니다. 병합이 아닙니다.
 * 그래서 reviewer 의 규칙만으로 완결적이어야 하고, 마지막 빗장도 직접 넣어야 합니다.
 *
 * 함정: permissions: [] 는 "아무 권한 없음" 이 아니라 "무제한" 입니다.
 * 빈 배열이니 어떤 규칙에도 안 걸리고 → 기본 allow → 전부 통과.
 * 잠그려는 의도로 [] 를 쓰면 정확히 반대 결과가 나옵니다.
 *
 * 또 하나: write 금지 규칙을 read 허용보다 먼저 둡니다. first-match-wins 이므로
 * 순서가 뒤집히면 의도가 흐려집니다.
 */
async function sol7() {
  console.log("\n===== [정답 7] =====");

  const agent = await createDeepAgent({
    model: MODEL,
    backend: new StateBackend(),
    checkpointer: new MemorySaver(),
    // 부모: /workspace 읽기·쓰기 허용
    permissions: [
      { operations: ["read", "write"], paths: ["/workspace/**"], mode: "allow" },
      { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
    ],
    subagents: [
      {
        name: "reviewer",
        description: "코드를 읽고 리뷰 의견만 제시한다. 파일을 절대 수정하지 않는다.",
        systemPrompt: "너는 코드 리뷰어다. 읽기만 하고 개선점을 목록으로 보고해라.",
        // 부모 규칙을 통째로 교체 — 이 배열만으로 완결적이어야 합니다
        permissions: [
          { operations: ["write"], paths: ["/**"], mode: "deny" }, // 쓰기 전면 금지
          { operations: ["read"], paths: ["/workspace/**"], mode: "allow" },
          { operations: ["read"], paths: ["/**"], mode: "deny" }, // 빗장
        ],
      },
    ],
  });

  console.log("reviewer: 쓰기 전면 금지 / /workspace 읽기만 허용");
  return agent;
}

/* ===== [정답 8] 승인 루프 =====
 * 실전 코드의 형태입니다. 포인트 세 가지:
 *
 * 1) while 로 도는 이유 — 한 번 재개했다고 끝이 아닙니다. 모델은 다음 턴에 또 도구를
 *    부를 수 있고, 그러면 __interrupt__ 가 또 옵니다. if 로 한 번만 처리하면
 *    두 번째 승인 요청을 놓치고 "왜 파일이 안 만들어지지?" 로 헤매게 됩니다.
 *
 * 2) 카운터 — 모델이 reject 를 받고 계속 재시도하면 무한 루프가 됩니다.
 *    사람이 붙어 있는 CLI 면 사람이 지쳐서 멈추지만, 자동화된 승인자라면 영원히 돕니다.
 *    상한을 두세요.
 *
 * 3) decisions 길이 — actionRequests 와 개수가 같아야 하고 순서도 같아야 합니다.
 *    map 으로 만드는 게 가장 안전합니다. 하나라도 빠지면 매칭이 어긋납니다.
 */
async function sol8() {
  console.log("\n===== [정답 8] =====");

  const agent = await createDeepAgent({
    model: MODEL,
    backend: new StateBackend(),
    checkpointer: new MemorySaver(),
    interruptOn: { write_file: true, edit_file: true },
  });

  const config = { configurable: { thread_id: "sol-8" } };

  let result = await agent.invoke(
    {
      messages: [
        { role: "user", content: "/workspace/a.txt 와 /workspace/b.txt 를 각각 만들어줘." },
      ],
    },
    config,
  );

  const MAX_RESUMES = 5;
  let resumes = 0;

  while (result.__interrupt__) {
    if (resumes >= MAX_RESUMES) {
      console.warn(`⚠️ 재개 ${MAX_RESUMES}회 초과 — 루프를 강제 종료합니다.`);
      break;
    }

    const req = result.__interrupt__[0] as Interrupt<HITLRequest>;
    // 개수와 순서를 맞추는 가장 안전한 방법: actionRequests 를 map 한다
    const resume: HITLResponse = {
      decisions: req.value.actionRequests.map(() => ({ type: "approve" as const })),
    };

    result = await agent.invoke(new Command({ resume }), config);
    resumes++;
  }

  console.log(`재개 횟수: ${resumes}`);
  console.log("파일 목록:", Object.keys(result.files ?? {}));
}

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

main().catch(console.error);