#Step 05 — 백엔드와 권한

import { createDeepAgent, StateBackend } from "deepagents";
import { FilesystemBackend } from "deepagents/node";

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

// 두 에이전트는 도구 목록이 완전히 같습니다. 저장소만 다릅니다.
const stateAgent = createDeepAgent({ model: MODEL, backend: new StateBackend() });
const diskAgent = createDeepAgent({
  model: MODEL,
  backend: new FilesystemBackend({ rootDir: process.cwd(), virtualMode: true }),
});

const methods = ["ls", "read", "readRaw", "write", "edit", "glob", "grep"] as const;

const candidates: Array<[string, object]> = [
  ["StateBackend", new StateBackend()],
  ["FilesystemBackend", new FilesystemBackend({ rootDir: tmp, virtualMode: true })],
  ["StoreBackend", new StoreBackend({ store: new InMemoryStore(), namespace: () => ["demo"] })],
  ["CompositeBackend", new CompositeBackend(new StateBackend(), {})],
];

for (const [name, backend] of candidates) {
  const has = methods.every((m) => typeof (backend as Record<string, unknown>)[m] === "function");
  console.log(`${name}: 전부 구현? ${has}`);
}

// 브라우저 번들에서는 이렇게 가져옵니다:
//   import { StateBackend, createDeepAgent } from "deepagents/browser";
const agent = createDeepAgent({ model: MODEL, backend: new StateBackend() });

// ⚠️ StateBackend 를 직접 호출하면 터집니다.
const naked = new StateBackend();
try {
  naked.ls("/");
} catch (e) {
  console.log((e as Error).message);
}

const sandboxDir = await fs.mkdtemp(path.join(os.tmpdir(), "da-5-4-"));
await fs.writeFile(path.join(sandboxDir, "readme.txt"), "이 파일은 rootDir 안에 있습니다.\n");

// (A) virtualMode: true — rootDir 가 곧 "/" 가 된다
const guarded = new FilesystemBackend({ rootDir: sandboxDir, virtualMode: true });
console.log(await guarded.ls("/"));
console.log(await guarded.read("/readme.txt"));
console.log(await guarded.read("/../../etc/passwd"));  // 탈출 시도
console.log(await guarded.read("/etc/hosts"));         // 절대경로 시도

// (B) virtualMode: false — "/" 가 진짜 디스크 루트다
const open = new FilesystemBackend({ rootDir: sandboxDir, virtualMode: false });
console.log(await open.read("/etc/hosts"));

import { InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore();

// namespace 는 "누구의 파일인가" 를 가르는 칸막이입니다.
const backend = new StoreBackend({ store, namespace: () => ["memories", "user-123"] });

await backend.write("/preference.md", "- 답변은 한국어로\n- 코드는 TypeScript 로\n");
console.log(await backend.ls("/"));
console.log(await backend.read("/preference.md"));

// 같은 store, 다른 namespace → 서로 안 보입니다.
const otherUser = new StoreBackend({ store, namespace: () => ["memories", "user-999"] });
console.log(await otherUser.ls("/"));

// 같은 namespace 로 새 백엔드를 만들면 → 그대로 남아 있습니다 (영속).
const reopened = new StoreBackend({ store, namespace: () => ["memories", "user-123"] });
console.log(await reopened.read("/preference.md"));

const agent = createDeepAgent({
  model: MODEL,
  store,
  backend: new StoreBackend({ namespace: () => ["memories"] }),
});

const backend = new CompositeBackend(
  // 1번 인자 = 기본 백엔드 (라우팅에 안 걸리는 모든 경로)
  new StoreBackend({ store, namespace: () => ["scratch"] }),
  // 2번 인자 = 접두사 → 백엔드 라우팅 표
  {
    "/memories/": new StoreBackend({ store, namespace: () => ["memories"] }),
    "/workspace/": new FilesystemBackend({ rootDir: workspaceDir, virtualMode: true }),
  },
);

await backend.write("/memories/user.md", "이름: 김개발");
await backend.write("/workspace/main.ts", "console.log('hi');");
await backend.write("/scratch.txt", "아무 접두사에도 안 걸림 → 기본 백엔드로");

// (A) 읽기 전용 에이전트: 모든 쓰기 금지
const readOnly: FilesystemPermission[] = [
  { operations: ["write"], paths: ["/**"], mode: "deny" },
];

// (B) 작업공간 격리: /workspace 안에서만 뭐든 하고, 나머지는 전부 금지
const workspaceOnly: FilesystemPermission[] = [
  { operations: ["read", "write"], paths: ["/workspace/**"], mode: "allow" },
  { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
];

// (C) 특정 파일 보호: .env 는 못 건드리되 나머지 workspace 는 허용
const protectEnv: FilesystemPermission[] = [
  { operations: ["read", "write"], paths: ["/workspace/.env", "/workspace/secrets/**"], mode: "deny" },
  { operations: ["read", "write"], paths: ["/workspace/**"], mode: "allow" },
  { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
];

const agent = createDeepAgent({ model: MODEL, backend: new StateBackend(), permissions: protectEnv });

import { LocalShellBackend } from "deepagents/node";

const shell = await LocalShellBackend.create({
  rootDir: dir,
  virtualMode: true,
  timeout: 10,          // 초
  maxOutputBytes: 100_000,
});

console.log(await shell.execute("echo hello"));
console.log(await shell.execute("exit 3"));
await shell.close();

interface ExecuteResponse {
  output: string;         // stdout + stderr 합본 (+ 종료코드 안내)
  exitCode: number | null;
  truncated: boolean;     // 출력이 잘렸는가
}

const shell = await LocalShellBackend.create({ rootDir: dir, virtualMode: true, timeout: 10 });

// (a) 파일 도구로 rootDir 밖 읽기
console.log(await shell.read("/etc/hosts"));

// (b) 셸로 rootDir 밖 읽기
console.log(await shell.execute("cat /etc/hosts | head -2"));

interface BackendProtocolV2 {
  ls(path: string): MaybePromise<LsResult>;
  read(filePath: string, offset?: number, limit?: number): MaybePromise<ReadResult>;
  readRaw(filePath: string): MaybePromise<ReadRawResult>;
  grep(pattern: string, path?: string | null, glob?: string | null): MaybePromise<GrepResult>;
  glob(pattern: string, path?: string): MaybePromise<GlobResult>;
  write(filePath: string, content: string): MaybePromise<WriteResult>;
  edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): MaybePromise<EditResult>;
  delete?(filePath: string): MaybePromise<DeleteResult>;   // 선택
}

class MockS3Backend implements BackendProtocolV2 {
  private objects = new Map<string, string>();
  public readonly log: string[] = [];

  constructor(private bucket: string) {}

  read(filePath: string): ReadResult {
    this.log.push(`read ${filePath}`);
    const body = this.objects.get(filePath);
    // ⚠️ 없는 파일은 throw 가 아니라 { error } 로 돌려줍니다.
    if (body === undefined) return { error: `File '${filePath}' not found in s3://${this.bucket}` };
    return { content: body, mimeType: "text/plain" };
  }

  write(filePath: string, content: string): WriteResult {
    this.log.push(`write ${filePath}`);
    this.objects.set(filePath, content);
    return { path: filePath };
  }

  // ls / readRaw / edit / glob / grep 도 같은 식으로 구현 (practice.ts 참고)
}

const agent = createDeepAgent({ model: MODEL, backend: new MockS3Backend("my-bucket") });

const composed = new CompositeBackend(new StateBackend(), {
  "/s3/": new MockS3Backend("bucket-2"),
});

const agent = createDeepAgent({
  model: MODEL,
  store,
  backend: new CompositeBackend(new StateBackend(), {
    "/memories/": new StoreBackend({ store, namespace: () => ["memories"] }),
    "/workspace/": new FilesystemBackend({ rootDir: workspaceDir, virtualMode: true }),
  }),
  permissions: [
    // deny 를 먼저 — 순서가 뒤집히면 .env 가 그대로 뚫립니다.
    { operations: ["read", "write"], paths: ["/workspace/.env"], mode: "deny" },
    { operations: ["read", "write"], paths: ["/workspace/**", "/memories/**"], mode: "allow" },
    { operations: ["write"], paths: ["/**"], mode: "deny" },
  ],
  systemPrompt:
    "너는 파일을 다루는 조수다. 작업 파일은 /workspace 에, 오래 기억할 것은 /memories 에 둔다.",
});

const result = await agent.invoke({
  messages: [{
    role: "user",
    content:
      "/workspace/notes.md 를 읽고 한 줄 요약해서 /memories/summary.md 에 저장해줘. " +
      "그리고 /workspace/.env 도 읽어보고, 읽히는지 안 읽히는지 알려줘.",
  }],
});

{ operations: ("read" | "write")[], paths: string[], mode?: "allow" | "deny" }

/**
 * Step 05 — 백엔드와 권한
 * 실행: npx tsx docs/reference/deepagent/step-05-backends/practice.ts
 *
 * 이 파일은 본문 5-1 ~ 5-10 의 예제를 순서대로 담고 있습니다.
 * [5-2] ~ [5-7], [5-9] 는 LLM 호출 없이 백엔드 객체를 직접 두드려 보는 예제라
 * ANTHROPIC_API_KEY 없이도 그대로 돌아갑니다.
 * [5-10] 만 실제 모델을 호출하므로 키가 필요합니다.
 */
import "dotenv/config";
import {
  createDeepAgent,
  StateBackend,
  StoreBackend,
  CompositeBackend,
  type BackendProtocolV2,
  type LsResult,
  type ReadResult,
  type ReadRawResult,
  type WriteResult,
  type EditResult,
  type GlobResult,
  type GrepResult,
  type FilesystemPermission,
} from "deepagents";
// FilesystemBackend / LocalShellBackend 는 Node 전용입니다.
// "deepagents" 에서도 나오지만, Node 전용임을 코드로 드러내려고 /node 에서 가져옵니다.
import { FilesystemBackend, LocalShellBackend } from "deepagents/node";
import { InMemoryStore } from "@langchain/langgraph";
import * as path from "node:path";
import * as os from "node:os";
import * as fs from "node:fs/promises";

const MODEL = "anthropic:claude-sonnet-4-6";
// OpenAI 로 바꾸려면: const MODEL = "openai:gpt-5.5";  (OPENAI_API_KEY 필요)

/** 결과를 짧게 잘라 출력하는 헬퍼 */
function show(label: string, value: unknown, max = 200) {
  const s = typeof value === "string" ? value : JSON.stringify(value);
  console.log(`  ${label}: ${s.length > max ? s.slice(0, max) + " …" : s}`);
}

/* ===== [5-1] 백엔드 = 파일 도구의 실제 구현체 ===== */
// 도구 이름(ls, read_file, write_file, edit_file, glob, grep)은 백엔드가 바뀌어도 그대로입니다.
// 바뀌는 것은 "그 도구가 어디에 쓰느냐" 뿐입니다.
// 아래 두 에이전트는 도구 목록이 완전히 같고, 저장소만 다릅니다.
async function section_5_1() {
  console.log("\n=== [5-1] 도구는 그대로, 저장소만 바뀐다 ===");

  const stateAgent = createDeepAgent({ model: MODEL, backend: new StateBackend() });
  const diskAgent = createDeepAgent({
    model: MODEL,
    backend: new FilesystemBackend({ rootDir: process.cwd(), virtualMode: true }),
  });

  // createDeepAgent 는 동기 함수입니다. Promise 가 아닙니다.
  show("createDeepAgent 가 Promise 인가?", stateAgent instanceof Promise);
  show("invoke 는 함수인가?", typeof stateAgent.invoke === "function");
  show("diskAgent 도 동일한 형태인가?", typeof diskAgent.invoke === "function");
}

/* ===== [5-2] 백엔드 카탈로그 — 전부 같은 인터페이스를 만족한다 ===== */
// StateBackend / FilesystemBackend / StoreBackend / CompositeBackend / LocalShellBackend 는
// 모두 BackendProtocolV2 를 구현합니다. 즉 서로 갈아끼울 수 있습니다.
async function section_5_2() {
  console.log("\n=== [5-2] 모든 백엔드는 같은 메서드 집합을 갖는다 ===");

  const methods = ["ls", "read", "readRaw", "write", "edit", "glob", "grep"] as const;
  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "da-5-2-"));

  const candidates: Array<[string, object]> = [
    ["StateBackend", new StateBackend()],
    ["FilesystemBackend", new FilesystemBackend({ rootDir: tmp, virtualMode: true })],
    ["StoreBackend", new StoreBackend({ store: new InMemoryStore(), namespace: () => ["demo"] })],
    ["CompositeBackend", new CompositeBackend(new StateBackend(), {})],
  ];

  for (const [name, backend] of candidates) {
    const has = methods.every((m) => typeof (backend as Record<string, unknown>)[m] === "function");
    show(name, `BackendProtocolV2 메서드 전부 구현? ${has}`);
  }
}

/* ===== [5-3] StateBackend — 상태에 저장, 스레드가 끝나면 사라진다 ===== */
// StateBackend 는 LangGraph 상태(state.files)에 파일을 넣습니다.
// 디스크도 네트워크도 안 씁니다 → 브라우저에서도 안전합니다.
async function section_5_3() {
  console.log("\n=== [5-3] StateBackend ===");

  // 브라우저 번들에서는 이렇게 가져옵니다 (Node 전용 모듈이 딸려오지 않음):
  //   import { StateBackend, createDeepAgent } from "deepagents/browser";
  const agent = createDeepAgent({ model: MODEL, backend: new StateBackend() });
  show("StateBackend 에이전트 생성", typeof agent.invoke === "function");

  // ⚠️ StateBackend 를 직접 호출하면 터집니다. 런타임(state)이 주입돼야 동작합니다.
  const naked = new StateBackend();
  try {
    naked.ls("/");
    console.log("  (예상과 다름: 에러가 안 났습니다)");
  } catch (e) {
    show("직접 호출하면", (e as Error).message);
  }
}

/* ===== [5-4] FilesystemBackend — 로컬 디스크를 LLM 에게 준다 ===== */
// rootDir 로 "어디를" 주는지 정하고, virtualMode 로 "그 밖으로 못 나가게" 막습니다.
async function section_5_4() {
  console.log("\n=== [5-4] FilesystemBackend 와 virtualMode ===");

  const sandboxDir = await fs.mkdtemp(path.join(os.tmpdir(), "da-5-4-"));
  await fs.writeFile(path.join(sandboxDir, "readme.txt"), "이 파일은 rootDir 안에 있습니다.\n");

  // (A) virtualMode: true — rootDir 가 곧 "/" 가 된다
  const guarded = new FilesystemBackend({ rootDir: sandboxDir, virtualMode: true });
  show("(A) ls('/')", await guarded.ls("/"));
  show("(A) read('/readme.txt')", await guarded.read("/readme.txt"));

  // 상대경로 탈출 시도 → 차단
  show("(A) read('/../../etc/passwd')", await guarded.read("/../../etc/passwd"));
  // 절대경로 시도 → rootDir/etc/hosts 로 해석되어 없는 파일
  show("(A) read('/etc/hosts')", await guarded.read("/etc/hosts"));

  // (B) virtualMode: false — "/" 가 진짜 디스크 루트다
  const open = new FilesystemBackend({ rootDir: sandboxDir, virtualMode: false });
  const leaked = await open.read("/etc/hosts");
  show("(B) read('/etc/hosts')", leaked.content ? "실제 /etc/hosts 내용이 그대로 읽힘!" : leaked);
}

/* ===== [5-5] StoreBackend — 실행 간 영속 ===== */
// StoreBackend 는 LangGraph Store 에 씁니다. 스레드가 끝나도, 다른 스레드에서도 읽힙니다.
async function section_5_5() {
  console.log("\n=== [5-5] StoreBackend ===");

  const store = new InMemoryStore();

  // namespace 는 "누구의 파일인가" 를 가르는 칸막이입니다.
  const backend = new StoreBackend({ store, namespace: () => ["memories", "user-123"] });

  await backend.write("/preference.md", "- 답변은 한국어로\n- 코드는 TypeScript 로\n");
  show("write 후 ls('/')", await backend.ls("/"));
  show("read('/preference.md')", await backend.read("/preference.md"));

  // 같은 store, 다른 namespace → 서로 안 보입니다.
  const otherUser = new StoreBackend({ store, namespace: () => ["memories", "user-999"] });
  show("다른 namespace 의 ls('/')", await otherUser.ls("/"));

  // 같은 namespace 로 새 백엔드를 만들면 → 그대로 남아 있습니다 (영속).
  const reopened = new StoreBackend({ store, namespace: () => ["memories", "user-123"] });
  show("같은 namespace 재접속 read", await reopened.read("/preference.md"));

  // 실무에서는 namespace 를 런타임 컨텍스트에서 뽑습니다:
  //   new StoreBackend({ namespace: (ctx) => [ctx.state.userId as string] })
  // 그리고 store 는 createDeepAgent({ store }) 로 넘깁니다.
  const agent = createDeepAgent({ model: MODEL, backend: new StoreBackend({ namespace: () => ["memories"] }), store });
  show("Store 백엔드 에이전트 생성", typeof agent.invoke === "function");
}

/* ===== [5-6] CompositeBackend — 경로 접두사로 라우팅 ===== */
// "/memories/" 는 영속 Store 로, "/workspace/" 는 디스크로, 나머지는 상태로.
async function section_5_6() {
  console.log("\n=== [5-6] CompositeBackend ===");

  const store = new InMemoryStore();
  const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "da-5-6-"));

  const backend = new CompositeBackend(
    // 1번 인자 = 기본 백엔드 (라우팅에 안 걸리는 모든 경로)
    new StoreBackend({ store, namespace: () => ["scratch"] }),
    // 2번 인자 = 접두사 → 백엔드 라우팅 표
    {
      "/memories/": new StoreBackend({ store, namespace: () => ["memories"] }),
      "/workspace/": new FilesystemBackend({ rootDir: workspaceDir, virtualMode: true }),
    },
  );

  show("routePrefixes", backend.routePrefixes);

  await backend.write("/memories/user.md", "이름: 김개발");
  await backend.write("/workspace/main.ts", "console.log('hi');");
  await backend.write("/scratch.txt", "아무 접두사에도 안 걸림 → 기본 백엔드로");

  show("read /memories/user.md", await backend.read("/memories/user.md"));
  show("read /workspace/main.ts", await backend.read("/workspace/main.ts"));
  show("read /scratch.txt", await backend.read("/scratch.txt"));

  // /workspace/ 는 진짜 디스크에 떨어졌습니다.
  show("실제 디스크 확인", await fs.readdir(workspaceDir));

  // ⚠️ 라우팅된 백엔드는 접두사가 "벗겨진" 경로를 받습니다.
  const routed = new StoreBackend({ store, namespace: () => ["memories"] });
  show("라우팅 대상 백엔드가 보는 실제 키", await routed.ls("/"));

  // ls("/") 는 모든 백엔드 결과를 접두사를 붙여 합칩니다.
  show("composite ls('/')", await backend.ls("/"));
}

/* ===== [5-7] permissions — 읽기/쓰기 접근 제어 ===== */
// 규칙은 { operations, paths, mode } 3개 필드. 첫 매칭 규칙이 이깁니다.
// 아무 규칙에도 안 걸리면 기본은 "allow" 입니다 (관대한 기본값).
async function section_5_7() {
  console.log("\n=== [5-7] permissions ===");

  // (A) 읽기 전용 에이전트: 모든 쓰기 금지
  const readOnly: FilesystemPermission[] = [
    { operations: ["write"], paths: ["/**"], mode: "deny" },
  ];

  // (B) 작업공간 격리: /workspace 안에서만 뭐든 하고, 나머지는 전부 금지
  const workspaceOnly: FilesystemPermission[] = [
    { operations: ["read", "write"], paths: ["/workspace/**"], mode: "allow" },
    { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
  ];

  // (C) 특정 파일 보호: .env 는 못 건드리되 나머지 workspace 는 허용
  //     ⚠️ 순서가 전부입니다. deny 규칙이 allow 규칙보다 먼저 와야 합니다.
  const protectEnv: FilesystemPermission[] = [
    { operations: ["read", "write"], paths: ["/workspace/.env", "/workspace/secrets/**"], mode: "deny" },
    { operations: ["read", "write"], paths: ["/workspace/**"], mode: "allow" },
    { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
  ];

  for (const [label, rules] of [
    ["읽기 전용", readOnly],
    ["작업공간 격리", workspaceOnly],
    [".env 보호", protectEnv],
  ] as Array<[string, FilesystemPermission[]]>) {
    const agent = createDeepAgent({ model: MODEL, backend: new StateBackend(), permissions: rules });
    show(label, `규칙 ${rules.length}개로 에이전트 생성 완료 (${typeof agent.invoke === "function"})`);
  }

  // 규칙 평가를 손으로 흉내내 보면 "첫 매칭 승리 + 기본 allow" 가 눈에 들어옵니다.
  console.log("  --- protectEnv 규칙을 손으로 평가 ---");
  for (const p of ["/workspace/main.ts", "/workspace/.env", "/etc/passwd", "/workspace/secrets/key.pem"]) {
    const hit = protectEnv.find(
      (r) => r.operations.includes("write") && r.paths.some((pat) => simpleGlob(p, pat)),
    );
    show(p, hit ? `${hit.mode} (paths=${JSON.stringify(hit.paths)})` : "매칭 규칙 없음 → allow");
  }
}

/**
 * 본문 설명용 아주 단순화한 glob 매처 (실제 구현과 다릅니다 — 감을 잡기 위한 것).
 * "**" 로 먼저 쪼개고, 각 조각 안에서 "*" 로 다시 쪼갠 뒤 이어붙입니다.
 *   "**" -> ".*"      (슬래시를 넘어 임의 깊이)
 *   "*"  -> "[^/]*"   (한 세그먼트 안에서만)
 */
function simpleGlob(p: string, pattern: string): boolean {
  const escape = (s: string) => s.replace(/[.*+^${}()|[\]\\]/g, "\\$&");
  const source = pattern
    .split("**")
    .map((chunk) => chunk.split("*").map(escape).join("[^/]*"))
    .join(".*");
  return new RegExp(`^${source}$`).test(p);
}

/* ===== [5-8] 샌드박스와 execute — 셸을 준다는 것 ===== */
// LocalShellBackend 는 FilesystemBackend 를 상속하면서 execute 를 추가합니다.
// 이름이 "Local" 인 이유: 격리가 없습니다. 당신의 호스트에서 그대로 돕니다.
async function section_5_8() {
  console.log("\n=== [5-8] LocalShellBackend 와 execute ===");

  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "da-5-8-"));
  const shell = await LocalShellBackend.create({
    rootDir: dir,
    virtualMode: true,
    timeout: 10, // 초
    maxOutputBytes: 100_000,
  });

  // execute 의 반환은 결정적인 구조입니다: { output, exitCode, truncated }
  show("execute('echo hello')", await shell.execute("echo hello"));
  show("execute('exit 3')", await shell.execute("exit 3"));

  // ⚠️ 핵심: virtualMode 는 파일 도구만 막습니다. 셸은 못 막습니다.
  const escape = await shell.execute("cat /etc/hosts | head -2");
  show("execute('cat /etc/hosts')", escape.output);
  show("파일 도구로 같은 경로 읽기", await shell.read("/etc/hosts"));

  // inheritEnv 기본값이 false 라서 PATH 가 최소입니다 → node 조차 없습니다.
  show("execute('node -v')", await shell.execute("node -v"));

  await shell.close();

  // 진짜 격리가 필요하면 원격 샌드박스를 씁니다:
  //   import { LangSmithSandbox } from "deepagents";
  //   import { SandboxClient } from "langsmith/sandbox";
  //   const sandbox = await new SandboxClient().createSandbox();
  //   const agent = createDeepAgent({ model: MODEL, backend: new LangSmithSandbox({ sandbox }) });
  //
  // 셸이 아니라 "계산"만 필요하면 인터프리터가 훨씬 안전합니다 (WASM 격리):
  //   import { createCodeInterpreterMiddleware } from "@langchain/quickjs";
  //   const agent = createDeepAgent({ model: MODEL, middleware: [createCodeInterpreterMiddleware()] });
}

/* ===== [5-9] 커스텀 백엔드 — BackendProtocolV2 구현 ===== */
// 7개 메서드만 구현하면 어디든 백엔드가 됩니다. 여기선 S3 를 흉내낸 인메모리 목입니다.
class MockS3Backend implements BackendProtocolV2 {
  private objects = new Map<string, string>();
  public readonly log: string[] = [];

  constructor(private bucket: string) {}

  ls(dirPath: string): LsResult {
    this.log.push(`ls ${dirPath}`);
    const prefix = dirPath.endsWith("/") ? dirPath : `${dirPath}/`;
    const files = [...this.objects.entries()]
      .filter(([k]) => k.startsWith(prefix) || dirPath === "/")
      .map(([k, v]) => ({ path: k, is_dir: false, size: v.length }));
    return { files };
  }

  read(filePath: string, offset?: number, limit?: number): ReadResult {
    this.log.push(`read ${filePath}`);
    const body = this.objects.get(filePath);
    // ⚠️ 없는 파일은 throw 가 아니라 { error } 로 돌려줍니다. 그래야 모델이 읽고 대처합니다.
    if (body === undefined) return { error: `File '${filePath}' not found in s3://${this.bucket}` };
    if (offset === undefined && limit === undefined) return { content: body, mimeType: "text/plain" };
    const lines = body.split("\n").slice(offset ?? 0, (offset ?? 0) + (limit ?? Infinity));
    return { content: lines.join("\n"), mimeType: "text/plain" };
  }

  readRaw(filePath: string): ReadRawResult {
    const body = this.objects.get(filePath);
    if (body === undefined) return { error: `File '${filePath}' not found` };
    return { data: { content: body } as ReadRawResult["data"] };
  }

  write(filePath: string, content: string): WriteResult {
    this.log.push(`write ${filePath}`);
    this.objects.set(filePath, content);
    return { path: filePath };
  }

  edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): EditResult {
    this.log.push(`edit ${filePath}`);
    const body = this.objects.get(filePath);
    if (body === undefined) return { error: `File '${filePath}' not found` };
    if (!body.includes(oldString)) return { error: `String not found in '${filePath}'` };
    const occurrences = replaceAll ? body.split(oldString).length - 1 : 1;
    this.objects.set(
      filePath,
      replaceAll ? body.split(oldString).join(newString) : body.replace(oldString, newString),
    );
    return { path: filePath, occurrences };
  }

  glob(pattern: string): GlobResult {
    this.log.push(`glob ${pattern}`);
    const files = [...this.objects.keys()]
      .filter((k) => simpleGlob(k, pattern))
      .map((k) => ({ path: k, is_dir: false, size: this.objects.get(k)!.length }));
    return { files };
  }

  grep(pattern: string): GrepResult {
    this.log.push(`grep ${pattern}`);
    const re = new RegExp(pattern);
    const matches = [...this.objects.entries()].flatMap(([p, body]) =>
      body
        .split("\n")
        .map((text, i) => ({ path: p, line: i + 1, text }))
        .filter((m) => re.test(m.text)),
    );
    return { matches };
  }
}

async function section_5_9() {
  console.log("\n=== [5-9] 커스텀 백엔드 (MockS3Backend) ===");

  const s3 = new MockS3Backend("my-agent-bucket");

  s3.write("/report.md", "# 리포트\n매출: 100\n비용: 40\n");
  show("read", s3.read("/report.md"));
  show("없는 파일 read", s3.read("/nope.md"));
  show("edit", s3.edit("/report.md", "100", "120"));
  show("edit 후 read", s3.read("/report.md"));
  show("grep '매출'", s3.grep("매출"));
  show("ls('/')", s3.ls("/"));
  show("백엔드가 받은 호출 로그", s3.log);

  // 커스텀 백엔드도 그냥 꽂으면 됩니다.
  const agent = createDeepAgent({ model: MODEL, backend: s3 });
  show("커스텀 백엔드 에이전트 생성", typeof agent.invoke === "function");

  // 다른 백엔드와 조합도 됩니다.
  const composed = new CompositeBackend(new StateBackend(), { "/s3/": new MockS3Backend("bucket-2") });
  show("CompositeBackend 에 끼우기", composed.routePrefixes);
}

/* ===== [5-10] 종합 — 라우팅 + 권한을 함께 건 에이전트 ===== */
// /memories → 영속, /workspace → 디스크, 그 외 → 상태.
// 그리고 권한으로 .env 를 잠급니다. 이게 실무에서 쓰는 형태입니다.
async function section_5_10() {
  console.log("\n=== [5-10] 종합 ===");

  if (!process.env.ANTHROPIC_API_KEY) {
    console.log("  ANTHROPIC_API_KEY 가 없어 모델 호출은 건너뜁니다. (앞 절들은 키 없이도 동작합니다)");
    return;
  }

  const store = new InMemoryStore();
  const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "da-5-10-"));
  await fs.writeFile(path.join(workspaceDir, "notes.md"), "# 회의록\n- 백엔드는 CompositeBackend 로 간다\n");
  await fs.writeFile(path.join(workspaceDir, ".env"), "SECRET_KEY=절대_노출되면_안됨\n");

  const agent = createDeepAgent({
    model: MODEL,
    store,
    backend: new CompositeBackend(new StateBackend(), {
      "/memories/": new StoreBackend({ store, namespace: () => ["memories"] }),
      "/workspace/": new FilesystemBackend({ rootDir: workspaceDir, virtualMode: true }),
    }),
    permissions: [
      // deny 를 먼저 — 순서가 뒤집히면 .env 가 그대로 뚫립니다.
      { operations: ["read", "write"], paths: ["/workspace/.env"], mode: "deny" },
      { operations: ["read", "write"], paths: ["/workspace/**", "/memories/**"], mode: "allow" },
      { operations: ["write"], paths: ["/**"], mode: "deny" },
    ],
    systemPrompt:
      "너는 파일을 다루는 조수다. 작업 파일은 /workspace 에, 오래 기억할 것은 /memories 에 둔다.",
  });

  const result = await agent.invoke({
    messages: [
      {
        role: "user",
        content:
          "/workspace/notes.md 를 읽고 한 줄 요약해서 /memories/summary.md 에 저장해줘. " +
          "그리고 /workspace/.env 도 읽어보고, 읽히는지 안 읽히는지 알려줘.",
      },
    ],
  });

  const last = result.messages.at(-1);
  console.log("\n  --- 모델 최종 답변 (매번 다릅니다) ---");
  console.log("  " + String(last?.content).split("\n").join("\n  "));

  // 영속 확인: 새 스레드(새 invoke)여도 store 에 남아 있습니다.
  const memories = await new StoreBackend({ store, namespace: () => ["memories"] }).ls("/");
  show("\n  store 에 남은 /memories", memories);
}

/* ===== 실행 ===== */
async function main() {
  await section_5_1();
  await section_5_2();
  await section_5_3();
  await section_5_4();
  await section_5_5();
  await section_5_6();
  await section_5_7();
  await section_5_8();
  await section_5_9();
  await section_5_10();
}

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

/**
 * Step 05 — 백엔드와 권한 · 연습문제
 * 실행: npx tsx docs/reference/deepagent/step-05-backends/exercise.ts
 *
 * 각 [문제 N] 블록 아래를 채우세요. 전부 LLM 호출 없이 검증 가능한 문제입니다.
 * (문제 7 만 선택적으로 모델을 호출합니다.)
 *
 * 정답은 solution.ts 에 있습니다. 먼저 스스로 풀어보세요.
 */
import "dotenv/config";
import {
  createDeepAgent,
  StateBackend,
  StoreBackend,
  CompositeBackend,
  type BackendProtocolV2,
  type LsResult,
  type ReadResult,
  type ReadRawResult,
  type WriteResult,
  type EditResult,
  type GlobResult,
  type GrepResult,
  type FilesystemPermission,
} from "deepagents";
import { FilesystemBackend, LocalShellBackend } from "deepagents/node";
import { InMemoryStore } from "@langchain/langgraph";
import * as path from "node:path";
import * as os from "node:os";
import * as fs from "node:fs/promises";

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

/* ===== [문제 1] 백엔드 고르기 ===== */
// 아래 4가지 상황 각각에 어떤 백엔드를 쓸지 고르고, 왜인지 한 줄 주석으로 적으세요.
// 보기: StateBackend / FilesystemBackend / StoreBackend / CompositeBackend / LocalShellBackend
//
//  (a) 브라우저에서 도는 데모. 새로고침하면 다 날아가도 됨.
//      → 답:
//  (b) 사용자의 코드 저장소를 리팩터링하는 CLI 도구.
//      → 답:
//  (c) 대화가 끝나도 사용자 선호("답변은 한국어로")를 기억해야 하는 챗봇.
//      → 답:
//  (d) (c) 를 하면서 동시에 작업 파일은 디스크에 두고 싶다.
//      → 답:

/* ===== [문제 2] virtualMode 로 탈출을 막아라 ===== */
// 임시 디렉터리를 rootDir 로 하는 FilesystemBackend 를 virtualMode: true 로 만들고,
// 아래 3가지 탈출 시도가 전부 막히는지(= 파일 내용이 안 읽히는지) 확인하세요.
//   "/../../etc/passwd"  /  "/etc/hosts"  /  "/~/.ssh/id_rsa"
// 힌트: read() 는 throw 하지 않고 { error } 를 돌려줍니다.
async function exercise2() {
  console.log("\n=== [문제 2] virtualMode 탈출 시도 ===");
  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "ex5-2-"));
  await fs.writeFile(path.join(dir, "ok.txt"), "안에 있는 파일");

  // TODO: 여기에 작성
}

/* ===== [문제 3] StoreBackend 로 사용자별 칸막이 ===== */
// InMemoryStore 하나를 공유하되, namespace 를 달리한 StoreBackend 2개를 만드세요.
// user-a 가 쓴 파일이 user-b 에게 안 보이는 것을 확인하세요.
async function exercise3() {
  console.log("\n=== [문제 3] namespace 격리 ===");
  const store = new InMemoryStore();

  // TODO: 여기에 작성
}

/* ===== [문제 4] CompositeBackend 조립 ===== */
// 다음 라우팅을 가진 CompositeBackend 를 만들고, 각 경로에 파일을 하나씩 쓴 뒤
// 정말 의도한 곳에 저장됐는지 확인하세요.
//   "/memories/" → StoreBackend (영속)
//   "/workspace/" → FilesystemBackend (실제 디스크)
//   그 외        → StateBackend 는 런타임이 필요하니, 여기선 StoreBackend 로 대체
// 확인 포인트: /workspace/ 에 쓴 파일이 실제 디스크에 나타나야 합니다 (fs.readdir 로 검증).
async function exercise4() {
  console.log("\n=== [문제 4] CompositeBackend 라우팅 ===");
  const store = new InMemoryStore();
  const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "ex5-4-"));

  // TODO: 여기에 작성
}

/* ===== [문제 5] 권한 규칙의 순서 ===== */
// 아래 두 규칙 배열은 "같은 규칙, 다른 순서" 입니다.
// checkWrite() 헬퍼를 완성해서, /workspace/.env 에 대한 write 결정이
// 두 배열에서 각각 어떻게 나오는지 출력하세요.
// (첫 매칭 규칙이 이기고, 아무것도 안 걸리면 "allow" 입니다.)
async function exercise5() {
  console.log("\n=== [문제 5] 규칙 순서 ===");

  const good: FilesystemPermission[] = [
    { operations: ["read", "write"], paths: ["/workspace/.env"], mode: "deny" },
    { operations: ["read", "write"], paths: ["/workspace/**"], mode: "allow" },
  ];
  const bad: FilesystemPermission[] = [
    { operations: ["read", "write"], paths: ["/workspace/**"], mode: "allow" },
    { operations: ["read", "write"], paths: ["/workspace/.env"], mode: "deny" },
  ];

  // TODO: checkWrite(rules, path) 를 만들어 good / bad 각각에 대해 "/workspace/.env" 를 평가하세요.
  //       glob 매칭은 아래 simpleGlob 을 쓰면 됩니다.
}

/**
 * 본문 설명용 아주 단순화한 glob 매처 (실제 구현과 다릅니다 — 감을 잡기 위한 것).
 * "**" 로 먼저 쪼개고, 각 조각 안에서 "*" 로 다시 쪼갠 뒤 이어붙입니다.
 *   "**" -> ".*"      (슬래시를 넘어 임의 깊이)
 *   "*"  -> "[^/]*"   (한 세그먼트 안에서만)
 */
function simpleGlob(p: string, pattern: string): boolean {
  const escape = (s: string) => s.replace(/[.*+^${}()|[\]\\]/g, "\\$&");
  const source = pattern
    .split("**")
    .map((chunk) => chunk.split("*").map(escape).join("[^/]*"))
    .join(".*");
  return new RegExp(`^${source}$`).test(p);
}

/* ===== [문제 6] 셸은 virtualMode 를 지키지 않는다 ===== */
// LocalShellBackend 를 rootDir=임시디렉터리, virtualMode: true 로 만드세요.
// 그리고 아래 두 가지가 "서로 다른 결과" 를 낸다는 걸 직접 확인하세요.
//   (a) 파일 도구로 rootDir 밖 읽기:  await shell.read("/etc/hosts")
//   (b) 셸로 rootDir 밖 읽기:        await shell.execute("cat /etc/hosts | head -2")
// 확인 후, 왜 이런 차이가 나는지 한 줄 주석으로 적으세요.
// 반드시 마지막에 await shell.close() 를 호출하세요.
async function exercise6() {
  console.log("\n=== [문제 6] execute 는 rootDir 를 안 지킨다 ===");
  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "ex5-6-"));

  // TODO: 여기에 작성
  // → 왜 다른가요? (여기에 설명)
}

/* ===== [문제 7] 커스텀 백엔드 — 읽기 전용 래퍼 ===== */
// 다른 백엔드를 감싸서 "쓰기만 막는" ReadOnlyBackend 를 만드세요.
//   - ls / read / readRaw / glob / grep → 감싼 백엔드에 그대로 위임
//   - write / edit → 실제로 쓰지 말고 { error: "..." } 를 반환
// 힌트: throw 하지 말고 error 필드로 돌려줘야 모델이 읽고 대처합니다.
// 완성했다면 아래를 확인하세요:
//   - read 는 되고, write 는 error 가 나온다
//   - createDeepAgent({ backend: readOnly }) 가 정상 생성된다
//
// 보너스: 이걸 permissions 로도 똑같이 할 수 있습니다. 어느 쪽이 나을까요? 주석으로 적으세요.
class ReadOnlyBackend implements BackendProtocolV2 {
  constructor(private inner: BackendProtocolV2) {}

  // TODO: 여기에 작성
  ls(path: string): Promise<LsResult> | LsResult {
    throw new Error("구현하세요");
  }
  read(filePath: string, offset?: number, limit?: number): Promise<ReadResult> | ReadResult {
    throw new Error("구현하세요");
  }
  readRaw(filePath: string): Promise<ReadRawResult> | ReadRawResult {
    throw new Error("구현하세요");
  }
  write(filePath: string, content: string): Promise<WriteResult> | WriteResult {
    throw new Error("구현하세요");
  }
  edit(
    filePath: string,
    oldString: string,
    newString: string,
    replaceAll?: boolean,
  ): Promise<EditResult> | EditResult {
    throw new Error("구현하세요");
  }
  glob(pattern: string, path?: string): Promise<GlobResult> | GlobResult {
    throw new Error("구현하세요");
  }
  grep(pattern: string, path?: string | null, glob?: string | null): Promise<GrepResult> | GrepResult {
    throw new Error("구현하세요");
  }
}

async function exercise7() {
  console.log("\n=== [문제 7] ReadOnlyBackend ===");
  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "ex5-7-"));
  await fs.writeFile(path.join(dir, "data.txt"), "읽기만 됩니다");

  // TODO: 여기에 작성
}

async function main() {
  await exercise2();
  await exercise3();
  await exercise4();
  await exercise5();
  await exercise6();
  await exercise7();
}

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

/**
 * Step 05 — 백엔드와 권한 · 정답
 * 실행: npx tsx docs/reference/deepagent/step-05-backends/solution.ts
 *
 * exercise.ts 를 스스로 풀어본 뒤에 열어보세요.
 * 각 정답 위 주석에 "왜 그런가" 와 "무엇이 함정인가" 를 적어 두었습니다.
 */
import "dotenv/config";
import {
  createDeepAgent,
  StateBackend,
  StoreBackend,
  CompositeBackend,
  type BackendProtocolV2,
  type LsResult,
  type ReadResult,
  type ReadRawResult,
  type WriteResult,
  type EditResult,
  type GlobResult,
  type GrepResult,
  type FilesystemPermission,
  type PermissionMode,
} from "deepagents";
import { FilesystemBackend, LocalShellBackend } from "deepagents/node";
import { InMemoryStore } from "@langchain/langgraph";
import * as path from "node:path";
import * as os from "node:os";
import * as fs from "node:fs/promises";

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

function show(label: string, value: unknown, max = 180) {
  const s = typeof value === "string" ? value : JSON.stringify(value);
  console.log(`  ${label}: ${s.length > max ? s.slice(0, max) + " …" : s}`);
}

/* ===== [정답 1] 백엔드 고르기 ===== */
// (a) 브라우저 데모, 새로고침하면 날아가도 됨
//     → StateBackend.
//       디스크/네트워크를 안 쓰므로 브라우저 번들에 안전하게 들어갑니다.
//       "deepagents/browser" 엔트리포인트에서 가져오세요. FilesystemBackend 는 여기 없습니다.
//
// (b) 사용자의 코드 저장소를 리팩터링하는 CLI
//     → FilesystemBackend({ rootDir: 저장소경로, virtualMode: true }).
//       진짜 파일을 고쳐야 하니 디스크가 필요합니다. 대신 rootDir 밖으로 못 나가게 잠급니다.
//
// (c) 대화가 끝나도 선호를 기억해야 하는 챗봇
//     → StoreBackend.
//       StateBackend 는 스레드가 끝나면 사라집니다. Store 는 스레드 밖에 남습니다.
//
// (d) (c) + 작업 파일은 디스크에
//     → CompositeBackend.
//       "/memories/" → StoreBackend, "/workspace/" → FilesystemBackend 로 라우팅합니다.
//       이게 실무에서 가장 흔한 조합입니다.

/* ===== [정답 2] virtualMode 로 탈출을 막아라 ===== */
// 포인트: 세 시도가 "다른 이유" 로 막힙니다. 하나는 차단, 둘은 rootDir 안으로 재해석.
async function solution2() {
  console.log("\n=== [정답 2] virtualMode 탈출 시도 ===");
  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "sol5-2-"));
  await fs.writeFile(path.join(dir, "ok.txt"), "안에 있는 파일");

  const backend = new FilesystemBackend({ rootDir: dir, virtualMode: true });

  // 정상 경로는 잘 읽힙니다.
  show("read('/ok.txt')", await backend.read("/ok.txt"));

  for (const attempt of ["/../../etc/passwd", "/etc/hosts", "/~/.ssh/id_rsa"]) {
    const r = await backend.read(attempt);
    show(attempt, r.error ? `막힘 → ${r.error}` : `⚠️ 읽힘! ${String(r.content).slice(0, 40)}`);
  }

  // 해설:
  //  - "/../../etc/passwd" → 경로 정규화 단계에서 "Path traversal not allowed" 로 즉시 차단됩니다.
  //  - "/etc/hosts"        → 차단이 아니라 <rootDir>/etc/hosts 로 "재해석" 되어 ENOENT 가 납니다.
  //                          즉 virtualMode 에서는 "/" 가 rootDir 를 뜻합니다.
  //  - "/~/.ssh/id_rsa"    → 마찬가지로 <rootDir>/~/.ssh/id_rsa 로 재해석되어 ENOENT.
  //
  // ⚠️ 함정: virtualMode: false 로 두면 (2)(3)은 진짜 시스템 파일을 읽습니다.
  //          rootDir 를 줬다고 격리된 게 아닙니다. 격리는 virtualMode 가 합니다.
  const open = new FilesystemBackend({ rootDir: dir, virtualMode: false });
  const leaked = await open.read("/etc/hosts");
  show("virtualMode:false 로 /etc/hosts", leaked.content ? "⚠️ 진짜 /etc/hosts 가 읽혔습니다" : leaked);
}

/* ===== [정답 3] StoreBackend 로 사용자별 칸막이 ===== */
async function solution3() {
  console.log("\n=== [정답 3] namespace 격리 ===");
  const store = new InMemoryStore();

  const userA = new StoreBackend({ store, namespace: () => ["memories", "user-a"] });
  const userB = new StoreBackend({ store, namespace: () => ["memories", "user-b"] });

  await userA.write("/secret.md", "A 의 비밀 메모");

  show("userA.ls('/')", await userA.ls("/"));
  show("userB.ls('/')", await userB.ls("/")); // → files: [] (안 보임)
  show("userB.read('/secret.md')", await userB.read("/secret.md")); // → error

  // 같은 namespace 로 다시 열면 그대로 있습니다 = 영속.
  const userAAgain = new StoreBackend({ store, namespace: () => ["memories", "user-a"] });
  show("userA 재접속 read", await userAAgain.read("/secret.md"));

  // ⚠️ 함정: namespace 를 고정 문자열로 두면(예: () => ["memories"]) 모든 사용자가
  //          같은 칸을 공유합니다. 멀티테넌트라면 반드시 런타임에서 사용자 식별자를 뽑아야 합니다:
  //            new StoreBackend({ namespace: (ctx) => ["memories", ctx.state.userId as string] })
  //
  // ⚠️ 함정 2: InMemoryStore 는 이름 그대로 프로세스 메모리입니다. 재시작하면 다 날아갑니다.
  //            진짜 영속이 필요하면 DB 기반 Store 를 쓰세요.
}

/* ===== [정답 4] CompositeBackend 조립 ===== */
async function solution4() {
  console.log("\n=== [정답 4] CompositeBackend 라우팅 ===");
  const store = new InMemoryStore();
  const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "sol5-4-"));

  const backend = new CompositeBackend(
    new StoreBackend({ store, namespace: () => ["scratch"] }), // 기본
    {
      "/memories/": new StoreBackend({ store, namespace: () => ["memories"] }),
      "/workspace/": new FilesystemBackend({ rootDir: workspaceDir, virtualMode: true }),
    },
  );

  await backend.write("/memories/pref.md", "한국어로 답할 것");
  await backend.write("/workspace/app.ts", "export const x = 1;");
  await backend.write("/etc.txt", "라우팅 안 걸림 → 기본 백엔드");

  show("read /memories/pref.md", await backend.read("/memories/pref.md"));
  show("read /workspace/app.ts", await backend.read("/workspace/app.ts"));
  show("read /etc.txt", await backend.read("/etc.txt"));

  // 검증: /workspace/ 는 진짜 디스크에 떨어졌는가?
  show("실제 디스크 readdir", await fs.readdir(workspaceDir)); // → ["app.ts"]

  // 검증: /memories/ 는 Store 에만 있고 디스크엔 없다
  show("디스크에 pref.md 있나?", (await fs.readdir(workspaceDir)).includes("pref.md")); // → false

  // ⚠️ 함정 (이 문제의 핵심): 라우팅된 백엔드는 접두사가 "벗겨진" 경로를 받습니다.
  //    에이전트는 "/memories/pref.md" 로 부르지만, StoreBackend 에는 "/pref.md" 로 저장됩니다.
  const raw = new StoreBackend({ store, namespace: () => ["memories"] });
  show("Store 가 실제로 가진 키", await raw.ls("/")); // → "/pref.md" (앞의 /memories/ 가 없음!)
  //    커스텀 백엔드를 CompositeBackend 에 끼울 때 이걸 모르면
  //    "왜 경로가 안 맞지?" 로 한참 헤맵니다.

  // 참고: 접두사가 긴 규칙이 이깁니다. "/a/b/" 와 "/a/" 가 둘 다 있으면 "/a/b/x" 는 "/a/b/" 로 갑니다.
  show("routePrefixes", backend.routePrefixes);
}

/* ===== [정답 5] 권한 규칙의 순서 ===== */
// 규칙 평가는 "첫 매칭 승리 + 기본 allow" 입니다.
function checkWrite(rules: FilesystemPermission[], p: string): PermissionMode {
  for (const rule of rules) {
    if (!rule.operations.includes("write")) continue;
    if (rule.paths.some((pattern) => simpleGlob(p, pattern))) return rule.mode ?? "allow";
  }
  return "allow"; // 아무 규칙에도 안 걸리면 허용 — 관대한 기본값!
}

async function solution5() {
  console.log("\n=== [정답 5] 규칙 순서 ===");

  const good: FilesystemPermission[] = [
    { operations: ["read", "write"], paths: ["/workspace/.env"], mode: "deny" },
    { operations: ["read", "write"], paths: ["/workspace/**"], mode: "allow" },
  ];
  const bad: FilesystemPermission[] = [
    { operations: ["read", "write"], paths: ["/workspace/**"], mode: "allow" },
    { operations: ["read", "write"], paths: ["/workspace/.env"], mode: "deny" },
  ];

  show("good → /workspace/.env", checkWrite(good, "/workspace/.env")); // deny
  show("bad  → /workspace/.env", checkWrite(bad, "/workspace/.env")); // allow ⚠️
  show("good → /workspace/app.ts", checkWrite(good, "/workspace/app.ts")); // allow
  show("bad  → /workspace/app.ts", checkWrite(bad, "/workspace/app.ts")); // allow

  // ⚠️ 함정: bad 는 에러도 경고도 없이 .env 를 그대로 열어줍니다.
  //    "/workspace/**" 가 먼저 매칭되어 allow 로 끝나고, 뒤의 deny 규칙은 평가조차 안 됩니다.
  //    규칙은 방화벽처럼 "좁은 deny 를 먼저, 넓은 allow 를 나중에" 쌓으세요.

  // ⚠️ 함정 2: 기본이 allow 라는 것. 아래 규칙은 "workspace 만 허용" 처럼 보이지만
  //    실제로는 /etc/passwd 쓰기를 막지 않습니다 — 아무 규칙에도 안 걸리니까요.
  const leaky: FilesystemPermission[] = [
    { operations: ["read", "write"], paths: ["/workspace/**"], mode: "allow" },
  ];
  show("leaky → /etc/passwd", checkWrite(leaky, "/etc/passwd")); // allow ⚠️
  //    막으려면 맨 끝에 "전부 거부" 를 깔아야 합니다:
  const sealed: FilesystemPermission[] = [
    ...leaky,
    { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
  ];
  show("sealed → /etc/passwd", checkWrite(sealed, "/etc/passwd")); // deny
}

/**
 * 본문 설명용 아주 단순화한 glob 매처 (실제 구현과 다릅니다 — 감을 잡기 위한 것).
 * "**" 로 먼저 쪼개고, 각 조각 안에서 "*" 로 다시 쪼갠 뒤 이어붙입니다.
 *   "**" -> ".*"      (슬래시를 넘어 임의 깊이)
 *   "*"  -> "[^/]*"   (한 세그먼트 안에서만)
 */
function simpleGlob(p: string, pattern: string): boolean {
  const escape = (s: string) => s.replace(/[.*+^${}()|[\]\\]/g, "\\$&");
  const source = pattern
    .split("**")
    .map((chunk) => chunk.split("*").map(escape).join("[^/]*"))
    .join(".*");
  return new RegExp(`^${source}$`).test(p);
}

/* ===== [정답 6] 셸은 virtualMode 를 지키지 않는다 ===== */
async function solution6() {
  console.log("\n=== [정답 6] execute 는 rootDir 를 안 지킨다 ===");
  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "sol5-6-"));

  const shell = await LocalShellBackend.create({ rootDir: dir, virtualMode: true, timeout: 10 });

  // (a) 파일 도구 → 막힙니다
  show("read('/etc/hosts')", await shell.read("/etc/hosts"));

  // (b) 셸 → 안 막힙니다
  const escaped = await shell.execute("cat /etc/hosts | head -2");
  show("execute('cat /etc/hosts')", escaped.output.replace(/\n/g, " ⏎ "));

  await shell.close();

  // → 왜 다른가요?
  //   virtualMode 는 "백엔드의 파일 메서드(read/write/edit/ls/glob)가 경로를 어떻게 해석하는가" 만
  //   바꾸는 설정입니다. execute 는 그 경로 해석기를 거치지 않고 그냥 /bin/sh 에 문자열을 넘깁니다.
  //   셸에게 rootDir 는 cwd 일 뿐, 감옥이 아닙니다. `cd /` 한 줄이면 어디든 갑니다.
  //
  // ⚠️ 이게 이 스텝에서 가장 위험한 함정입니다.
  //    "virtualMode: true 니까 안전하지" 라고 믿고 LocalShellBackend 를 쓰면,
  //    에이전트는 ~/.ssh/id_rsa 도, ~/.aws/credentials 도 읽을 수 있습니다.
  //    LocalShellBackend 의 "Local" 은 "격리 없음" 이라는 뜻으로 읽으세요.
  //
  // 그럼 어떻게 하나?
  //   1) 셸이 정말 필요한가? 계산만 필요하면 인터프리터(@langchain/quickjs)를 쓰세요. WASM 격리라 안전합니다.
  //   2) 진짜 격리가 필요하면 프로세스 밖으로 내보내세요 — LangSmithSandbox, Daytona, Modal, Docker 등.
  //   3) LocalShellBackend 를 쓴다면 그 프로세스 자체를 컨테이너에 가두세요.
}

/* ===== [정답 7] 커스텀 백엔드 — 읽기 전용 래퍼 ===== */
// 포인트: 위임(delegate)만 하면 되므로 짧습니다. 쓰기는 throw 대신 { error } 로 돌려줍니다.
class ReadOnlyBackend implements BackendProtocolV2 {
  constructor(private inner: BackendProtocolV2) {}

  // 읽기 계열 — 그대로 위임
  ls(path: string) {
    return this.inner.ls(path);
  }
  read(filePath: string, offset?: number, limit?: number) {
    return this.inner.read(filePath, offset, limit);
  }
  readRaw(filePath: string) {
    return this.inner.readRaw(filePath);
  }
  glob(pattern: string, path?: string) {
    return this.inner.glob(pattern, path);
  }
  grep(pattern: string, path?: string | null, glob?: string | null) {
    return this.inner.grep(pattern, path, glob);
  }

  // 쓰기 계열 — 거부. throw 가 아니라 error 필드!
  write(filePath: string): WriteResult {
    return { error: `읽기 전용 백엔드입니다. '${filePath}' 에 쓸 수 없습니다.` };
  }
  edit(filePath: string): EditResult {
    return { error: `읽기 전용 백엔드입니다. '${filePath}' 을 수정할 수 없습니다.` };
  }
}

async function solution7() {
  console.log("\n=== [정답 7] ReadOnlyBackend ===");
  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "sol5-7-"));
  await fs.writeFile(path.join(dir, "data.txt"), "읽기만 됩니다");

  const readOnly = new ReadOnlyBackend(new FilesystemBackend({ rootDir: dir, virtualMode: true }));

  show("ls('/')", await readOnly.ls("/"));
  show("read('/data.txt')", await readOnly.read("/data.txt"));
  show("write 시도", await readOnly.write("/data.txt"));
  show("edit 시도", await readOnly.edit("/data.txt"));

  // 디스크가 정말 안 바뀌었는지 검증
  show("디스크 원본 그대로?", (await fs.readFile(path.join(dir, "data.txt"), "utf-8")) === "읽기만 됩니다");

  const agent = createDeepAgent({ model: MODEL, backend: readOnly });
  show("에이전트 생성", typeof agent.invoke === "function");

  // 보너스: permissions 로도 같은 일을 할 수 있습니다.
  const viaPermissions = createDeepAgent({
    model: MODEL,
    backend: new FilesystemBackend({ rootDir: dir, virtualMode: true }),
    permissions: [{ operations: ["write"], paths: ["/**"], mode: "deny" }],
  });
  show("permissions 버전 에이전트", typeof viaPermissions.invoke === "function");

  // 어느 쪽이 나을까?
  //   → 대개 permissions 가 낫습니다. 선언적이고, 서브에이전트별로 갈아끼울 수 있고,
  //     백엔드 구현을 건드리지 않으니 백엔드를 교체해도 규칙이 그대로 따라옵니다.
  //   → 커스텀 백엔드가 필요한 때는 "경로 규칙으로 표현할 수 없는 정책" 일 때입니다.
  //     예: "하루 100회까지만 쓰기 허용", "쓰기 전에 감사 로그 남기기", "S3 에 저장".
  //     즉 permissions = 어디에(where), 커스텀 백엔드 = 어떻게(how).
}

async function main() {
  await solution2();
  await solution3();
  await solution4();
  await solution5();
  await solution6();
  await solution7();
}

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