파일 도구: Read, Write, Edit

파일 도구 시스템은 세 가지 도구로 구성되지만, 하나의 핵심 불변식을 공유합니다:

"모든 쓰기 작업은 대상 파일의 사전 읽기를 요구한다."

세 도구의 능력 비교:

페이지네이션

Read는 기본적으로 2,000줄을 반환합니다. offset과 limit 파라미터로 특정 범위를 지정할 수 있습니다.

토큰 제한 — 2단계 게이팅

파일 크기 검증은 두 단계로 이루어집니다:

1. 빠른 대략적 추정: 파일 크기에서 토큰 수를 빠르게 추정
2. 정확한 토큰 카운트: 초과 시 API를 호출하여 정확한 토큰 수 확인

25,000 토큰을 초과하면 MaxFileReadTokenExceededError가 발생합니다. 잘라내기 대신 오류를 반환하는 것이 핵심 설계 결정입니다 — 잘라내기는 약 25K 토큰의 응답을 생성하지만, 오류는 약 100바이트만 차지합니다.

이미지 지원

PNG, JPG, GIF, WebP를 지원합니다. sharp 또는 image-processor-napi를 통해 선택적으로 리사이즈합니다.

PDF 지원

pages 파라미터로 읽을 페이지 범위를 지정하며, 호출당 최대 20페이지로 제한됩니다.

중복 제거

readFileState에 파일 메타데이터(경로, mtime, 내용 해시)를 저장합니다. 동일 파일을 다시 읽을 때 mtime이 일치하면 전체 내용 대신 약 100바이트의 스텁을 반환합니다.

차단 디바이스 경로

/dev/zero, /dev/random, /dev/urandom 등 무한 스트림을 생성하는 디바이스 경로는 차단됩니다. 단, /dev/null은 허용됩니다(빈 내용을 반환).

Write는 파일의 전체 내용을 교체합니다. 기존 파일에 대해서는 반드시 사전 Read가 완료되어야 합니다.

3가지 실패 모드

1. 세션 내 읽기 없음 (errorCode 2): 해당 파일에 대한 Read 호출이 세션에서 한 번도 실행되지 않은 경우
2. 부분 읽기 (errorCode 2): offset/limit으로 일부만 읽은 후 Write 시도 — isPartialView: true로 설정되어 전체 읽기로 인정되지 않음
3. 읽기 후 파일 수정됨 (errorCode 3): Read 이후 외부 프로세스가 파일을 수정한 경우 — mtime 비교로 감지

줄 끝 정책

Write는 항상 LF(\n)로 저장합니다. 이전 접근법에서 CRLF를 보존하면 bash 스크립트가 조용히 손상되는 문제가 발견되어, LF 강제 정책으로 변경되었습니다.

원자적 쓰기 시퀀스

Write의 실행 순서는 다음과 같습니다:

1. mkdir — 대상 디렉토리가 없으면 생성
2. fileHistoryTrackEdit — 변경 이력 추적
3. 동기 읽기 + 낡음 검사 — 최종 시점에서 파일이 변경되지 않았는지 확인
4. 디스크 쓰기 — 실제 파일 작성

// Write 원자적 시퀀스 (간소화)
await mkdir(dirname(filePath), { recursive: true })
fileHistoryTrackEdit(filePath, oldContent)

// 낡음 검사: 마지막 Read 이후 파일이 변경되었는지 확인
const currentStat = statSync(filePath)
if (currentStat.mtimeMs !== readFileState.mtimeMs) {
  throw new ToolError('File modified since last read', { errorCode: 3 })
}

writeFileSync(filePath, normalizedContent)

Edit은 정확한 문자열 치환을 수행하며, 차이분만 전송합니다. 전체 파일 대신 변경할 부분만 보내므로 토큰 효율이 높습니다.

고유성 요구

old_string이 파일 내에서 여러 위치에 일치하면 오류 코드 9가 반환됩니다. 어떤 위치를 교체해야 할지 모호하기 때문입니다. 단, replace_all: true를 설정하면 모든 일치 위치를 교체합니다.

따옴표 정규화

Edit의 가장 정교한 기능 중 하나입니다. 두 단계로 동작합니다:

1. findActualString(): 파일 내용과 검색 문자열을 모두 직선 따옴표(ASCII)로 정규화하여 일치 위치를 찾음
2. preserveQuoteStyle(): new_string에 원본 파일의 둥근 따옴표(curly quotes) 스타일을 적용하여 기존 스타일 보존

// 따옴표 정규화 흐름
// 파일 내용: "Hello, world"  (둥근 따옴표)
// old_string:  "Hello, world"  (직선 따옴표)

// 1단계: findActualString() — 양쪽 모두 직선 따옴표로 정규화
normalize("\u201cHello, world\u201d") → "\"Hello, world\""
normalize("\"Hello, world\"")    → "\"Hello, world\""
// 일치! 원본 위치 기록

// 2단계: preserveQuoteStyle() — new_string에 둥근 따옴표 스타일 적용
// new_string: "Hi, world" → \u201cHi, world\u201d

새 파일 생성

old_string: ""으로 설정하면 비존재 파일을 생성할 수 있습니다. 빈 문자열은 빈 파일에 일치하므로, 새 파일의 전체 내용을 new_string으로 전달합니다.

탈위생화 테이블

정확한 일치가 실패하면 위생화된 문자열을 원래 형태로 되돌리며 재시도합니다:

• <fnr> → <function_results>
• 기타 시스템이 위생화한 문자열 패턴들

후행 공백 제거

Edit은 기본적으로 후행 공백을 제거하지만, .md 및 .mdx 파일은 제외됩니다. Markdown에서 줄 끝의 두 칸 공백은 하드 줄바꿈(<br>)을 의미하므로 제거하면 문서 형식이 깨집니다.

선택 가이드: 기존 파일에서 소수의 줄만 변경할 때는 Edit이 토큰 효율적입니다. 파일의 대부분을 변경하거나 새 파일을 처음부터 작성할 때는 Write가 직관적입니다.

읽기-쓰기 계약은 4단계로 실행됩니다:

1. Read가 readFileState에 저장: 파일 경로, mtime, 내용 해시, 부분 읽기 여부(isPartialView)를 기록
2. validateInput()이 검사: Write/Edit 호출 시 해당 파일에 대한 readFileState 존재 여부와 부분 읽기 여부를 확인
3. call()이 원자적 낡음 검사 재실행: 실제 쓰기 직전에 파일의 현재 mtime을 readFileState와 비교하여 중간에 변경되지 않았는지 최종 확인
4. Write/Edit 실행 및 readFileState 갱신: 쓰기 완료 후 새로운 mtime과 내용으로 readFileState를 업데이트

// 읽기-쓰기 계약 4단계

// 1단계: Read가 상태 저장
readFileState[filePath] = {
  mtimeMs: stat.mtimeMs,
  contentHash: hash(content),
  isPartialView: !!(offset || limit),
}

// 2단계: validateInput()에서 사전 검사
if (!readFileState[filePath]) {
  throw new ToolError('Must read file before writing', { errorCode: 2 })
}
if (readFileState[filePath].isPartialView) {
  throw new ToolError('Partial read insufficient', { errorCode: 2 })
}

// 3단계: call()에서 원자적 낡음 검사
const current = statSync(filePath)
if (current.mtimeMs !== readFileState[filePath].mtimeMs) {
  throw new ToolError('File changed since read', { errorCode: 3 })
}

// 4단계: 쓰기 후 상태 갱신
writeFileSync(filePath, newContent)
readFileState[filePath] = { mtimeMs: statSync(filePath).mtimeMs, ... }