Flue 에이전트 내구성 실행: 재시도를 켜는 쪽과 끄는 쪽의 기준, 구현 사례 두 가지 비교

TypeScript 에이전트 하네스 프레임워크인 Flue 로 에이전트 두 개를 만들었는데, 재시도 설정이 정반대가 되었습니다. Slack 비서는 Flue 의 내구성 실행을 그대로 쓰고, PR 리뷰어는 일부러 껐습니다. 둘을 가른 기준은 «다시 실행되면 무엇이 두 번 일어나는가»라는 질문 하나였습니다.

이 글은 먼저 Flue 가 어떤 프레임워크인지를 뒤의 두 구현을 읽는 데 필요한 만큼만 정리하고, 그다음 두 에이전트가 같은 약속을 어떻게 다르게 다뤘는지 적은 기록입니다. 마지막에는 리뷰어가 자기 자신의 업그레이드를 검토했을 때 드러난, 설계끼리 어긋난 지점을 적었습니다.

먼저 밝혀 둘 것이 있습니다. Slack 비서는 코드가 병합되었지만 기본으로 꺼져 있어서, 설정을 켜기 전에는 실행되지 않습니다. 실제 Slack 발송과 실제 모델 과금은 테스트하지 않았으므로 이 글에는 운영 결과가 없습니다. 이 글에서 다루는 PR 리뷰어의 결과도 한 PR 에 남은 리뷰 댓글 두 개입니다. 아래 내용은 효과의 증거라기보다, 무엇을 걱정해서 그렇게 만들었는지에 대한 설명으로 읽어 주시면 좋겠습니다. 사용한 버전은 @flue/runtime 2.3.0 이고, 두 에이전트 모두 Node 에서 start() 로 런타임을 직접 띄웁니다.

Flue 는 무엇인가 — 하네스를 받는 함수

Flue 는 Astro 제작진이 만든 오픈소스 에이전트 프레임워크입니다(Apache-2.0). 스스로를 «The Agent Harness Framework», «Not another SDK»라고 부릅니다. 문서의 설명을 따르면 Flue 에이전트는 Claude Code 같은 «제대로 된 에이전트»를 지향하고, 오픈 에이전트 하네스인 Pi 위에 지어졌습니다. 각 에이전트는 도구·스킬·지침, 그리고 붙이면 샌드박스까지 갖춘 하네스를 받습니다. 문서는 에이전트를 LLM + 하네스 + 특화된 맥락으로 정의합니다.

에이전트 함수와 훅 — 프롬프트는 매 턴 다시 그려집니다

에이전트 함수는 시스템 프롬프트 문자열을 반환하는 평범한 JS 함수이고, 모델을 부르기 직전마다, 즉 매 턴 다시 실행됩니다. 문서는 일부러 React 컴포넌트의 렌더 함수에 빗댑니다. 능력은 함수 본문에서 useModel·useTool·useSandbox 같은 훅을 불러 하나씩 붙이고, useAgentStart 는 메시지가 전달될 때마다 실행되는 이벤트 훅입니다. 에이전트는 항상 ID 로 초기화되고 인스턴스는 ID 별로 영속됩니다.

매 턴 다시 렌더되기 때문에 useTool 을 조건문으로 감싸면 그 조건이 참인 턴에만 도구가 존재합니다. 문서는 «마운트되지 않은 도구는 호출할 수 없다 — 쓰지 말라는 지시보다 강한 보장이다»라고 적습니다. 파일·셸 같은 기본 도구도 샌드박스를 붙였을 때만 생깁니다.

웹훅·큐·채팅 이벤트처럼 비동기로 들어오는 입력은 dispatch() 로 대화에 넣습니다. dispatch 는 응답을 기다리지 않고 접수 영수증(receipt)을 돌려주고, 결과는 init(agent, { id }) 로 얻은 핸들에서 read(receipt) 로 읽습니다. 접수와 결과 읽기가 갈라져 있다는 점이 내구성 이야기의 출발점입니다.

접수된 일은 정확히 하나의 끝에 도달한다

Flue 의 내구성은 문서가 accepted-work 라고 부르는 약속으로 요약됩니다. 모든 입력은 submission 으로 접수되어 모델 작업 전에 먼저 기록되고, «접수된 submission 은 몇 번 크래시가 나든 정확히 하나의 내구 종료 상태(completed·failed·aborted)에 도달한다»고 약속합니다. 처리는 attempt 단위이고, 중단되면 복구가 기록된 증거만 보고 새 attempt 를 잡습니다. 기본값은 submission 당 10 attempts, 1시간이고, 에이전트 함수의 durability 정적 속성으로 바꿉니다.

도구는 보수적으로 다룹니다. 결과가 기록된 도구 호출은 다시 실행하지 않고, 결과가 기록되지 않은 일반 도구 호출도 다시 실행하지 않은 채 «결과를 알 수 없음» 오류로 처리합니다. 부수효과가 이미 일어났는지 런타임이 알 방법이 없기 때문입니다. 문서는 이 원칙을 «at-least-once execution over exactly-once recording»이라고 적습니다. 내구적으로 커밋된 일은 다시 돌지 않고, 커밋 전에 끊긴 일(모델 턴이나 이벤트 훅 콜백 같은 것)은 다음 attempt 에서 다시 돈다는 뜻입니다.

durable 도구와 step.do

결제·프로비저닝·여러 단계 동기화처럼 중간에 끊겨도 끝까지 완료되어야 하는 일을 하는 도구는 durable: true 로 선언할 수 있습니다. 그러면 복구 때 «결과 모름»으로 처리하는 대신 호출을 다시 실행합니다. 이때 run 은 step 을 받고, 부수효과를 step.do(name, fn) 로 감쌉니다. 다시 실행할 때 이미 완료된 step 은 기록된 값을 돌려줄 뿐 실행하지 않습니다.

다만 step 은 기록은 정확히 한 번, 실행은 최소 한 번입니다. 함수가 끝난 뒤 기록이 남기 전에 크래시가 나면 그 step 은 다시 돕니다. 그래서 외부 효과를 감싼 step 은 각각 멱등해야 합니다.

내구성 밖에 있는 것

내구성이 닿지 않는 곳도 문서에 적혀 있습니다. 하나는 진행 중인 로컬 promise 입니다. read() 를 기다리던 프로세스가 죽으면 그 promise 는 사라지지만, dispatch 영수증을 저장해 두면 어느 프로세스에서든 read(receipt) 로 같은 submission 에 다시 붙을 수 있습니다. 다른 하나는 외부 부수효과입니다. 결제, 앱 DB 의 행, Slack 메시지는 바깥 시스템에 남습니다. Flue 는 도구가 돌았다는 사실과 반환값을 기록할 뿐 효과 자체는 기록하지 않으니, 외부 효과는 멱등하게 설계하고 toolCallId 같은 안정적인 ID 로 키를 잡으라고 문서가 권합니다.

정리하면 Flue 는 끊긴 일을 «다시 시도»하는 쪽을 기본값으로 둔 프레임워크입니다. 그 기본값이 고마운 쪽과 위험한 쪽이 있었고, 제가 만든 두 에이전트가 정확히 그 양쪽에 섰습니다.

Slack 비서 — 내구성 실행을 그대로 쓴 쪽

첫 번째 에이전트는 허용된 운영자 한 명이 비공개 Slack 채널에서 봇을 멘션하면, 같은 스레드에서 업무용 외부 서비스의 요청함을 조회해 주는 비서입니다. 요청을 조회하고, 요청마다 판단 근거를 설명하고, 기존 통계 스냅샷을 해석하고, 요청받은 답장 초안을 저장합니다. 후속 질문이나 초안 수정도 같은 스레드에서 이어 갑니다. 기존 MCP 서버를 대체하지 않는 독립 Node 서비스입니다.

이 비서가 할 수 없는 일은 지시로 막지 않고 도구를 아예 두지 않는 방식으로 막았습니다. 외부 서비스로 무언가를 보내기, 요청의 상태를 바꾸기, 비용이 드는 기능 쓰기가 그렇습니다. 발송을 요청하면 «초안까지만 가능하다»고 답합니다.

이 비서에 필요했던 것은 스레드마다 이어지는 대화, 재시작 뒤에도 이어 읽기, 서명이 검증된 Slack 수신이었는데, 셋 다 Flue 가 기본으로 주는 기능이었습니다. 전체 흐름은 이렇습니다.

Slack Events → 서명 검증·허용 목록 → SQLite inbox(ACK 전 기록) → Flue 대화
                                                        ↓ 제한된 도구 5개
                                                 백엔드 전용 내부 API(권한 매 요청 확인)

Slack 스레드 하나가 Flue 대화 인스턴스 하나입니다. 인스턴스 ID 는 Slack 앱·워크스페이스·채널·운영자·봇·백엔드 주소·소유 계정·스레드 ts 를 이어 붙인 값의 SHA-256 이라서, 채널이나 운영자, 백엔드가 바뀌면 같은 스레드라도 다른 대화가 됩니다. Flue 는 대화와 도구 실행을 SQLite 파일에 보관하므로 프로세스를 다시 띄워도 맥락이 이어집니다.

봇에는 관리자 토큰이나 외부 서비스의 자격증명을 주지 않았습니다. 백엔드는 별도 비밀값과 고정된 관리자 계정을 확인하고, 매 요청마다 그 계정의 활성·승인·권한을 다시 읽습니다.

ACK 전에 기록하고, 넘치면 503 을 돌려줍니다

Slack 수신은 @flue/slack 의 createSlackChannel 에 맡겼습니다. 이 패키지는 정확한 요청 바이트로 서명을 검증하고, 5분 타임스탬프 창과 URL 검증을 내부에서 처리합니다. 패키지 자체는 무상태라 재전송 중복은 dispatch 의 idempotencyKey 로 수렴시키라고 안내하고, 발신 기능은 없어 공식 @slack/web-api 를 직접 씁니다.

이벤트를 받으면 ACK 를 돌려주기 전에 앱의 SQLite inbox 에 먼저 기록합니다. 같은 메시지가 mention 이벤트와 message 이벤트로 두 번 오는 경우나 Slack 의 재전송은 메시지 ts 로 만든 ID 로 걸러 냅니다. 수용량(24시간 50개, 대기 10개, 스레드당 40개)을 넘으면 ACK 전에 503 을 돌려 Slack 이 나중에 다시 보내게 했습니다. 이 한도는 금액 한도가 아니고, 모델 공급자 쪽 사용 한도는 따로 설정합니다.

영수증을 먼저 저장합니다

inbox 의 다음 작업은 dispatch({ message, idempotencyKey: 작업ID }) 로 넣고, 돌려받은 submission ID 를 먼저 inbox 에 저장한 다음 read(receipt) 로 답을 기다립니다. 프로세스가 죽더라도 다음 실행이 저장된 영수증으로 같은 submission 에 다시 붙습니다. 로컬 promise 는 내구적이지 않으니 영수증을 저장해 두라는 문서의 권고를 그대로 따른 것입니다. 다만 시도 예산은 대화의 성격에 맞게 기본값 10회·1시간에서 durability = { maxAttempts: 2, timeoutMs: 120000 }, 즉 최대 2회 시도로 줄였고, 읽기 대기도 135초 신호로 끊습니다.

초안 저장만 durable 도구로 만들었습니다

도구는 읽기·수집 도구 넷과 초안 저장 하나입니다. 읽기·수집 도구 가운데 새로고침도 새 요청을 저장하지만, 이미 있는 요청은 덮어쓰지 않고 새 요청만 덧붙이므로 다시 돌아도 같은 상태로 수렴합니다. 다시 돌았을 때 중복이 생길 수 있는 것은 초안 저장뿐이어서, 이 도구만 durable: true 로 선언하고 저장 요청을 step.do 로 감쌌습니다.

useTool({
  name: 'save_draft',
  durable: true,
  description: '요청받은 답장 초안/수정본을 새 draft 버전으로 저장. 발송 기능 없음.',
  input: v.object({
    itemId: v.pipe(v.string(), v.regex(/^[\w-]{1,64}$/)),
    bodyMd: v.pipe(v.string(), v.minLength(1), v.maxLength(12000)),
  }),
  run: (ctx) =>
    ctx.step.do('save', async () =>
      JSON.stringify(
        await client.request(
          'drafts',
          {
            ...ctx.data,
            // 같은 도구 호출이 다시 실행돼도 같은 키 → 백엔드가 중복 INSERT 를 막는다
            requestId: createHash('sha256').update(`${id}:${ctx.toolCallId}`).digest('hex'),
          },
          ctx.signal
        )
      )
    ),
});

핵심은 백엔드로 보내는 요청 ID 를 sha256(인스턴스ID:toolCallId) 로 만든 데 있습니다. step 은 최소 한 번 실행되므로 같은 도구 호출이 복구 과정에서 다시 돌 수 있지만, 키가 같으니 백엔드가 고정 키와 DB 트랜잭션 잠금으로 같은 초안을 두 번 INSERT 하지 않습니다. 사용자가 수정을 요청하면 그것은 새 도구 호출이라 새 ID 와 새 버전이 생깁니다. 문서가 권하는 대로 외부 효과를 멱등하게 만들고 키를 toolCallId 로 잡은 셈입니다.

Slack 발신은 «모름»으로 남깁니다

Slack 으로 답을 보내는 일은 Flue 의 도구가 아니라 에이전트 밖의 코드이고, 따라서 내구성 밖의 부수효과입니다. 여기에는 다른 규칙을 적용했습니다.

const receipt =
  job.receipt || (await handle.dispatch({ message: job.text, idempotencyKey: job.id })).submissionId;
inbox.dispatched(job.id, receipt); // 영수증 먼저 저장 → 재시작 뒤 같은 submission 에 다시 붙는다
const reply = (await handle.read(receipt, { signal: AbortSignal.timeout(135_000) })).text;
inbox.ready(job.id, reply);

await checkChannel(); // 복구된 답도 현재 채널 상태·권한을 다시 통과해야 한다
await access();

inbox.status(job.id, 'delivering');
try {
  await slack.chat.postMessage({ channel, thread_ts: job.thread, text: safeSlackText(reply) });
  inbox.status(job.id, 'done');
} catch {
  inbox.status(job.id, 'unknown'); // 보냈는지 모른다 → 자동으로 다시 보내지 않는다
}

보내기 직전에 상태를 delivering 으로 바꾸고, 발신이 성공하면 done 으로 바꿉니다. 발신 도중 연결이 끊기면 unknown 이 되고, 발신 중에 프로세스가 죽었다가 다시 뜨면 시작할 때 남아 있는 delivering 을 전부 unknown 으로 바꿉니다. 그리고 unknown 은 자동으로 다시 보내지 않습니다. 사람이 스레드를 확인하고, 필요하면 새 메시지로 다시 요청합니다.

같은 답이 두 번 가는 것보다 한 번 빠지는 쪽을 택한 것입니다. 수신자 쪽 멱등성에 기대는 at-least-once 공식이 언제 깨지는지, 그리고 «모른다»를 하나의 상태로 두는 일에 대해서는 AI 에이전트 중계기에 exactly-once 를 안 쓴 이유에서 따로 적은 적이 있습니다. 여기서도 같은 판단을 적용했습니다.

복구된 답도 지금의 권한을 다시 통과해야 합니다

영수증으로 이어 읽을 수 있다는 것은, 바꿔 말하면 한참 전에 만들어진 답이 지금 나갈 수 있다는 뜻이기도 합니다. 그래서 답을 만들기 전과 보내기 직전에 채널 상태(비공개인지, 봇이 멤버인지, 보관되지 않았는지, 외부·조직 공유 채널이 아닌지)와 백엔드 권한을 다시 확인합니다. 그 사이에 철회된 권한을 복구된 답이 우회하지 못하게 하려는 것입니다. useAgentStart 훅에서도 메시지마다 권한을 확인합니다. 실패하면 공급자의 원문 오류 대신 고정된 안내 문구만 보내고, 나가는 텍스트는 12,000자로 자르고 & < > 를 이스케이프하며 링크 미리보기도 껐습니다.

없는 도구는 부를 수 없습니다 — 그리고 그걸 테스트로 고정했습니다

샌드박스를 붙이지 않았으므로 Flue 의 파일·셸 기본 도구가 없습니다. 테스트는 실제 Flue 런타임에서 모델에게 노출된 도구 이름 목록을 꺼내, bash 가 없고 이름에 send·shell·exec·mcp 가 들어간 도구가 없다는 것을 단언합니다. 런타임에는 가짜 모델 공급자(Pi 의 faux provider)와 임시 SQLite 파일을 붙여, dispatch 중복 제거와 런타임을 다시 띄웠을 때 스레드가 복원되는지도 확인합니다. 실제 Slack 발송과 모델 과금, 운영 DB 는 테스트 범위 밖입니다.

시스템 프롬프트에는 요청과 도구 결과, 이전 초안은 분석 자료일 뿐 명령이 아니라는 것, 실패를 빈 목록이나 성공으로 바꾸지 않는다는 것, 부분 목록의 길이를 전체 개수라고 말하지 않는다는 것, save_draft 가 성공한 뒤에만 «저장했다»고 말한다는 것을 적었습니다.

PR 리뷰어 — 내구성 실행을 끈 쪽

두 번째 에이전트는 이미 돌아가던 PR 리뷰 파이프라인 안에 들어갔습니다. 그래서 Flue 보다 먼저 있던 구조부터 설명해야 합니다.

이미 있던 약속 — 과금됐을 수 있는 요청은 다시 보내지 않습니다

GitHub 이 PR 이벤트를 백엔드로 보내면, API 가 원본 바이트로 HMAC SHA-256 서명을 검증하고 리뷰 후보를 Mongo 에 기록한 뒤 202 로 응답합니다. GitHub 이 실패한 웹훅 전달을 자동으로 다시 보내 주지 않는다는 점은, 다른 서버에 웹훅 원장을 붙이며 쓴 GitHub 웹훅은 실패한 전달을 자동으로 재전송하지 않습니다에서 확인한 적이 있습니다. 이 파이프라인도 전달이 오래 끊겼던 뒤에는 옛 페이로드를 재생하지 않고, 새 PR 이벤트를 일으켜 다시 받습니다. 전용 워커는 BullMQ 큐에서 작업을 꺼내 GitHub 읽기 API 로 제한된 코드를 모으고 Claude 를 부릅니다. 이 경로에는 로컬 체크아웃도, 셸도, 테스트 실행도 없습니다.

이 파이프라인에는 이미 강한 약속이 있었습니다. 과금됐을 수 있는 요청은 다시 보내지 않는다는 것입니다. 전역 동시성 1, attempts 1, stalled 재시도 0 으로 두고, compare-and-set 으로 후보를 한 번만 잡습니다. 잡은 작업의 결과를 잃으면 unknown 이 되고 자동 유료 재시도로 돌아가지 않습니다. 결제 거절이 관측되면 모든 리뷰 호출을 멈추고 사람이 재개합니다. 연속 push 를 묶으려고 base/head 스냅샷마다 기본 180초를 기다렸다가 처리하고, 유료 호출 직전에 PR 이 아직 그 스냅샷인지 다시 확인합니다.

Flue 의 재시도는 여기서 이중 과금이 됩니다

Flue 의 장점인 자동 복구는 이 약속과 정면으로 부딪힙니다. 중단된 submission 을 새 attempt 로 다시 잡는 일이, 리뷰에서는 곧 같은 요청에 돈을 두 번 내는 일이기 때문입니다. 게다가 내구 큐는 이미 Mongo 와 BullMQ 에 있었습니다. 여기에 Flue 의 SQLite 를 또 두면 큐가 두 개가 되고, 어느 쪽이 실행의 주인인지가 흐려집니다.

그래서 Flue 는 도구 루프로만 빌리기로 했습니다. 작업마다 런타임을 새로 띄우고 끝나면 닫습니다. 저장소는 sqlite(':memory:') 라서 소스 원문이 디스크에 남지 않고, 끊긴 유료 작업을 Flue 가 되살릴 근거 자체가 남지 않습니다. 시도 예산은 durability = { maxAttempts: 1, timeoutMs: 420000 }, 즉 단 1회 시도입니다.

한 가지 더 손댄 곳이 있습니다. Flue 안에는 «일시적 오류면 재시도»를 판단하는 분류기가 있어서, 오류 메시지를 review_terminal_failure 라는 일반 문구로 바꿔 내보냅니다. 코드 주석에는 «Never expose a transient keyword to Flue's internal model retry classifier.»라고 적어 두었습니다.

모델 호출은 호스트가 쥡니다

모델 계층도 Flue 에 넘기지 않았습니다. Pi 의 createProvider 로 pr-review 라는 사용자 정의 공급자를 만들고, 그 stream 이 백엔드가 넘겨준 turn() 함수를 부르게 했습니다. 그래서 결제 중단 확인, 프롬프트 캐시, thinking 블록 처리, 자격증명 같은 기존 Claude 호출부가 그대로 백엔드에 남고, 에이전트 패키지에는 공급자도 네트워크도 자격증명도 디스크 저장소도 없습니다. 코드 주석의 표현으로는 «the host owns all capabilities»입니다. Claude 5.5 는 thinking 이 기본으로 켜져 있어서, 백엔드가 서명된 thinking 블록을 도구 연속 호출 때 원본 그대로 되돌려 주고, Flue 와 로그에는 텍스트와 도구 동작만 넘깁니다. 자동 압축은 compaction: false 로 껐습니다.

Flue 패키지가 ESM 전용이라 CommonJS 로 컴파일되는 NestJS 백엔드에 바로 붙지 않았습니다. 리뷰 에이전트를 별도 패키지로 빼서 tsup 으로 CJS 빌드를 하되 Flue·Pi·valibot 은 external 로 두고 함수 안에서 await import() 로 불러왔습니다. 또 Flue 가 돌려주는 답 텍스트에는 도구 턴의 서술이 섞여 있어서, 마지막 공급자 턴의 텍스트만 따로 잡아 JSON 으로 파싱합니다.

마지막 턴에는 도구를 마운트하지 않습니다

리뷰어의 도구는 read_context 하나입니다. 고정된 head SHA 의 소스·테스트 파일만 파일당 8KiB 까지 읽고, 같은 경로를 다시 요청하면 거부합니다. 샌드박스가 없으니 셸도 테스트 실행도 없습니다.

여기서 매 턴 다시 렌더된다는 성질이 쓰입니다. 마지막 턴, 또는 종료 사유가 생긴 턴에는 read_context 를 아예 마운트하지 않습니다. 도구가 없으니 모델은 최종 JSON 을 낼 수밖에 없습니다.

function reviewer() {
  flue.useModel(`pr-review/${model}`, { compaction: false });
  if (calls < MAX_TURNS - 1 && !stopReason) {
    flue.useTool({ name: 'read_context', /* …처음 보는 내용을 읽었을 때만 progress++ */ });
  }
  return `${system}\n…마지막 응답은 지정 JSON 객체만 출력한다.`;
}
reviewer.durability = { maxAttempts: 1, timeoutMs: 420_000 };

«마지막 턴에는 도구를 쓰지 말라»고 프롬프트에 적는 것과, 그 턴에 도구가 존재하지 않는 것은 다릅니다. 앞의 것은 모델이 따를지 말지를 고르지만, 뒤의 것은 고를 대상이 없습니다. 다만 도구 집합이 바뀌면 공급자 쪽 프롬프트 캐시가 무효화될 수 있다고 문서가 적고 있어서, 마지막 턴이 캐시 측면에서는 손해일 수 있습니다.

진전이 있을 때만 연장합니다

처음 리뷰어는 3턴, 파일 4개로 고정돼 있었습니다. 복잡한 PR 은 3턴에서 탐색이 끊겼고, 후속 push 가 오면 전체 diff 를 다시 모델에 보냈습니다. 이를 바꾼 방향은 진전이 있을 때만 연장하는 것입니다. 새 파일 근거가 생기는 동안에만 최대 8번의 모델 응답, 서로 다른 파일 12개까지 늘리고, «진전»은 처음 보는 내용을 읽었을 때만 셉니다. 내용의 SHA-256 으로 판단하므로 같은 경로나 같은 내용, 읽기 실패는 진전이 아닙니다. 진전이 없거나 한도에 닿으면 도구를 걷고 최종화하니, 8턴은 상한이지 고정 횟수가 아닙니다.

대신 예산을 두었습니다. 작업당 기본값은 누적 30만 토큰(캐시 읽기·쓰기 포함), 추정 2달러, 에이전트 단계 360초이고, 이 금액은 청구서가 아니라 로컬 입장 한도입니다. 다음 호출을 보내기 전에 보수적으로 입장 심사를 합니다.

const reserveMs = reserveNext ? Math.min(120_000, this.limits.durationMs / 3) : 0;
// UTF-8 바이트 수 + 여유분: 일부러 보수적으로, 캐시 적중을 가정하지 않는다
const input = Buffer.byteLength(JSON.stringify(body)) + 4096;
const output = 8192;
const factor = reserveNext ? 2 : 1; // 이번 호출 + 최종 호출 한 번
if (this.tokens + factor * (input + output) > this.limits.tokens) return 'token_limit';

입력은 요청 본문의 UTF-8 바이트에 여유분 4,096 을 더한 값으로, 출력은 8,192 토큰으로 잡습니다. «이번 호출 + 최종 호출 한 번», 즉 2회분이 들어가지 않으면 도구 없이 최종 답만 요청하고, 1회분도 들어가지 않으면 모델을 더 부르지 않고 «미완료» 결과를 남깁니다. 마감 시각에는 진행 중인 HTTP 호출을 끊고, 과금됐을 수 있는 중단 요청은 unknown 으로 남긴 채 다시 보내지 않습니다.

후속 push 쪽은 증분 재검토로 바꿨습니다. 같은 기준으로 완료한 이전 리뷰가 있고, 이전 head 가 현재 head 의 조상임을 GitHub 이 증명하면, 변경분과 이전 지적을 중심으로 다시 봅니다. 이전 지적은 ID 별로 resolved·still_present·uncertain 으로 다시 판정합니다. 리베이스나 규칙 변경처럼 그 전제가 깨지면 전체 리뷰로 돌아갑니다. 증분 결과는 PR 전체를 다시 봤다고 주장하지 않도록 언제나 partial 로 표시합니다.

근거는 근거로만 씁니다

리뷰 규칙은 PR 이 아니라 고정된 base SHA 에서 읽습니다. PR 이 규칙 파일을 고쳐 자기에게 유리하게 만들 수 없게 하려는 것입니다. 이 블로그 저장소 전용 프로필은 루트의 REVIEW.md 를 읽고, 리뷰 모듈의 파일이 바뀐 PR 이면 그 모듈의 REVIEW.md 도 읽습니다. CI 도 근거로만 씁니다. 체크 메타데이터를 스냅샷할 뿐 워크플로를 실행하지 않고, testedSha 는 일부러 null 로 둡니다. 초록 체크는 커버리지나 머지 준비의 증명이 아닙니다.

결과는 base/head 스냅샷마다 PR 댓글 하나로 남깁니다. 본문은 «정적 검토 자료이며 테스트 통과나 병합 승인이 아니다»로 시작하고, 지적과 불확실성, 그리고 검토하지 못한 목록을 담습니다. 호스트가 감지한 제약이 하나라도 있으면 지적이 0건이어도 coverage 를 partial 로 표시합니다. 댓글 게시 응답을 잃어 확인이 안 되면 여기서도 unknown 으로 멈추고 자동 재게시는 하지 않습니다.

리뷰어가 자기 업그레이드를 검토했을 때

위의 적응형 연장과 증분 재검토를 추가하는 PR 을, 아직 3턴 고정인 이전 버전의 리뷰어가 두 번 검토했습니다. 첫 커밋 뒤에 한 번, 수정 커밋 뒤에 한 번입니다. 두 번 다 completed 였고, partial 이었고, 지적은 한 건씩이었습니다.

두 번 모두 16개 파일 가운데 13개만 검토했습니다. 빠진 3개는 입력 예산 때문이었는데, 하필 증분 기준을 고르는 핵심 처리 코드, 그리고 리뷰어 자신의 Flue 런타임 파일과 그 테스트였습니다. 리뷰어는 이를 숨기지 않고 검토 누락과 불확실성으로 적었습니다. CI 는 아직 대기·진행 중이었고 testedSha 가 null 이라, 테스트 통과의 근거가 아니며 지적이 한 건뿐이라는 것이 병합 승인을 뜻하지 않는다는 문장도 함께 있었습니다.

첫 번째 지적 — 짧은 시간 한도

첫 검토의 지적(P3)은 시간 예약에 관한 것이었습니다. 검토 시간 한도를 허용 범위(10초~360초) 안에서 120초 미만으로 설정하면, 다음 턴을 위해 늘 120초를 예약하는 계산 때문에 첫 턴부터 탐색 도구가 꺼지고 모든 리뷰가 부분 결과가 된다는 내용이었습니다. 예약 시간을 한도에 비례하게 잡고 경계값 테스트를 추가하라는 제안이었고, 이 제안은 그대로 반영되었습니다. 위 코드의 Math.min(120_000, this.limits.durationMs / 3) 가 그 결과입니다.

두 번째 지적 — 바이트를 토큰으로 본 대가

두 번째 검토의 지적(P2)은 심각도가 한 단계 높았습니다. 입력 UTF-8 바이트를 그대로 토큰으로 보고, 다음 호출 때 (본문 + 여유분 + 출력)을 두 배로 예약하는 기본 예산에서는, 30만 토큰 한도일 때 본문이 약 137,700바이트를 넘으면 첫 턴부터 token_limit 이 난다는 것이었습니다. 검산해 보면 300,000 ÷ 2 − 4,096 − 8,192 = 137,712 입니다.

리뷰어의 설명은 이렇게 이어졌습니다. 수집 입력의 상한이 128KiB 인 데다 시스템 프롬프트와 도구 스키마, JSON 이스케이프가 더해지므로 큰 PR 은 이 선을 쉽게 넘고, 두 번째 턴에서도 실제 사용량에 다시 (본문 + 약 12k)×2 가 더해져 대부분 막힌다는 것입니다. 그래서 이 PR 이 노린 «복잡한 PR» 에서 오히려 파일 읽기가 0~1회로 줄어, 도구 턴 두 번을 보장하던 이전의 3턴 고정보다 회귀이고, «최대 8턴·12파일 자동 연장»은 기본 설정에서 사실상 닿지 않는다는 것이 리뷰어의 결론이었습니다. 바이트에서 토큰으로 바꾸는 계수를 현실적으로 잡거나, 직전 실제 사용량을 기준으로 증가분만 예약하고, 140~190KiB 본문으로 회귀 테스트를 하라는 제안이 붙어 있었습니다.

이 글을 쓰는 시점의 코드에는 바이트 기준 추정과 2배 예약이 그대로 남아 있습니다. 코드 주석은 여전히 «일부러 보수적으로, 캐시 적중을 가정하지 않는다»고 적고 있습니다.

어긋난 지점 — 두 원칙이 같은 숫자를 두고 다툽니다

돌이켜 생각해보면, 이 지적이 가리킨 것은 계산 실수 하나라기보다 두 원칙의 충돌이었습니다. 비용 상한을 절대 넘지 않게 하려는 보수적 추정과, 근거가 있을 때 더 탐색하게 하려는 적응형 연장이 입장 심사라는 같은 숫자를 두고 다투고 있었습니다. 둘 다 따로 보면 옳은 원칙입니다. 그런데 보수성의 여유분은 입력이 클수록 커지고, 연장이 정말 필요한 것도 입력이 큰 PR 입니다. 작은 PR 에서는 아무 문제가 없다가, 연장이 필요한 바로 그 자리에서 먼저 막히는 구조였습니다.

그리고 그 사실을 찾아낸 것은, 연장 기능이 들어가기 전의 리뷰어가 보수적인 입력 예산 때문에 자기 런타임 파일을 보지 못한 채로였습니다. 리뷰어가 «못 본 것»을 목록으로 남기게 해 둔 덕분에, 이 결과를 «지적 1건, 문제없음»이 아니라 «16개 중 13개 파일 범위에서 지적 1건»으로 읽을 수 있었습니다. 부분을 부분이라고 말하게 만든 장치가 쓸모를 보인 자리였습니다.

정리 — 같은 프레임워크, 정반대의 재시도

두 에이전트의 재시도·저장소·부수효과 처리 비교

항목	Slack 비서	PR 리뷰어
실행 형태	상주 서비스, 스레드마다 이어지는 대화	작업마다 띄웠다 닫는 일회용 런타임
Flue 저장소	SQLite 파일(재시작 뒤 복원)	`:memory:`(작업이 끝나면 소멸)
최대 시도	maxAttempts 2, 120초	maxAttempts 1, 420초 + 재시도 분류기 회피
내구 inbox 의 주인	앱의 SQLite inbox + Flue	Mongo + 큐(Flue 는 루프만)
모델 공급자	Pi 내장 공급자	백엔드 호출부를 감싼 사용자 정의 공급자
도구	조회·수집 4 + durable 저장 1	파일 읽기 1(조건부 마운트)
Flue 밖 부수효과	Slack 발신 → unknown, 재발신 없음	PR 댓글·과금 호출 → unknown, 재전송 없음
멱등 키	`sha256(인스턴스 ID:toolCallId)`	스냅샷(저장소·PR·base·head·정책 지문)

결국 내구성은 켜고 끄는 기능이 아니라, «다시 실행되면 무엇이 두 번 일어나는가»에 대한 약속이라는 결론에 닿았습니다. 대화는 영수증으로 다시 이어 읽어도 손해가 없지만, 과금된 리뷰 요청은 다시 보내면 돈이 두 번 나갑니다. 그래서 같은 프레임워크 위에서 한쪽은 SQLite 파일과 최대 2회 시도를, 다른 쪽은 메모리 SQLite 와 단 1회 시도를 골랐습니다. 그리고 두 에이전트의 공통점은 오히려 Flue 밖에 있었습니다. Slack 발신, PR 댓글, 과금된 호출처럼 Flue 가 기록하지 않는 부수효과는 둘 다 «모름»을 상태로 두고 자동으로 다시 보내지 않습니다.

Flue 덕분에 «마지막 턴엔 도구 없음» 같은 조건을 프롬프트 지시가 아니라 코드 구조로 표현할 수 있었고, 실제 런타임에 가짜 공급자를 붙여 재시작 복원까지 테스트할 수 있었습니다. 걸린 점도 있었습니다.

ESM 전용이라 CommonJS 백엔드에 붙이려고 별도 패키지와 동적 import 다리가 필요했습니다.
답 텍스트에 도구 턴의 서술이 섞여, 최종 턴만 따로 파싱해야 했습니다.
내장 재시도 분류기가 «재전송 금지» 약속과 부딪혀, 오류 문구를 일부러 일반화했습니다.
도구 집합이 바뀌면 프롬프트 캐시가 무효화될 수 있어, 도구 없는 마지막 턴에 비용이 따를 수 있습니다.
기본 내구성 값(10회·1시간)은 Slack 대화에도, 리뷰에도 너무 컸습니다.

프레임워크의 재시도가 닿는 곳은 프레임워크가 기록하는 범위까지였고, 그 바깥에서 무엇이 두 번 일어날지는 만드는 쪽이 에이전트마다 따로 물어야 했습니다.

Flue 로 에이전트 두 개를 만들고, 하나는 내구성을 껐습니다