설정¶

flower에는 설정 파일 형식이 없고, 실제로 동작하는 설정 서브커맨드도 없다 —— 모든 설정은 환경 변수와 .env 파일, 그리고 Python 쪽에서만 넘길 수 있는 정책 객체 몇 개가 전부다. 이 페이지는 다섯 군데에 흩어진 것들을 한 장으로 모은다: 변수 하나하나, 인증 정보를 어떤 순서로 찾는지, .env가 어떤 문법을 인정하는지, setting_sources=[]가 정확히 무엇을 격리하는지, 한 번 실행하면 디스크에 무엇이 남는지, session store 세 층이 각각 무엇을 버리는지, 네트워크가 끊겼을 때 어떻게 기다리는지. 용어는 전부 용어집을 따른다.

환경 변수 전체 표¶

다섯 그룹이다: flower가 직접 읽는 인증 정보와 엔드포인트, 모델 선택, 경로 탐색, 동작 스위치, 그리고 flower가 agent 하위 프로세스에 써 주는 것. 마지막 그룹은 네가 설정할 필요가 없다 —— 설정해도 덮어써진다.

인증 정보와 엔드포인트¶

둘 다 설정하지 않으면(또는 둘 다 빈 문자열이면) check_credentials()가 그 네 줄짜리 에러를 반환하고, Runtime.__init__도 RuntimeError를 던진다(env.py:184-194;runtime.py:156-158).

모델 선택¶

flower는 이 중 세 개만 자기 판단에 쓰고, 나머지는 로드해서 SDK로 그대로 넘긴다.

flower setup에서 모델 이름을 채우면 ANTHROPIC_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL、 ANTHROPIC_DEFAULT_SONNET_MODEL 세 개를 함께 쓴다(cli.py:1383-1385).

경로와 탐색¶

동작 스위치¶

둘 다 비상구다: 설정하지 않는 게 정상이고, 설정하는 건 flower가 뭔가 하나를 덜 하게 하려는 것이다. 비어 있지 않은 아무 값이나 넣으면 발효되며, 값 자체는 파싱하지 않는다(update.py:121;cli.py:1413).

git 소스에서 실행한 flower는 자동 업데이트의 영향을 받지 않으며, FLOWER_NO_UPDATE는 이 경우 no-op이다 —— 업데이트 명령 단계에서 저장소에 .git이 있음을 알아채면 바로 None을 반환한다(update.py:83-87).

flower가 agent 하위 프로세스에 써 주는 것¶

이 셋은 CompactPolicy.env()가 생성해서 ClaudeAgentOptions.env에 넣는 것이며(agent.py:48-58、:241-245), harness 내장 compact를 제어한다. shell에서 직접 설정해도 의미가 없다 —— 실제로 발효되는 것은 flower가 하위 프로세스에 전달하는 쪽이다.

컨테이너 래퍼가 읽는 것¶

이 둘은 flower 본체가 읽는 게 아니라 docker/flowerbox라는 shell 래퍼가 읽는다. 전체 사용법은 배포를 보라.

.env의 키는 위의 것들로 제한되지 않는다. 파서는 모든 k=v 줄을 os.environ에 로드하며 화이트리스트를 두지 않는다 (env.py:30、:102-107). 위 9개 인증 키로 이루어진 KNOWN은 두 군데에서만 작용한다: ~/.claude 설정을 차용할 때의 화이트리스트(env.py:72), 그리고 -v로 시작할 때 describe()가 출력하는 필드 범위(env.py:205).

인증 정보 탐색 우선순위¶

load_dotenv()에 경로를 넘기지 않으면 아래 순서로 존재하는 모든 파일을 차례로 읽어 들인다 (env.py:45-53、:78-112):

1. 프로세스 환경 변수 —— 언제나 최우선. 어떤 .env도 이미 export된 값을 덮지 못한다.(env.py:91)
2. $FLOWER_ENV가 가리키는 파일 —— 설정했을 때만 존재하는 항목.(env.py:48-49)
3. $PWD/.env —— 현재 작업 디렉터리. 어느 프로젝트로 cd하든 가까운 것을 읽는다.(env.py:50)
4. ${XDG_CONFIG_HOME:-~/.config}/flower/.env —— 사용자당 하나인 전역 위치. flower setup이 쓰는 곳이 여기다.(env.py:51、:39-42)
5. 소스 저장소 루트의 .env —— flower/core/env.py에서 세 단계 위. 소스에서 실행할 때만 존재한다. pip / pipx / uv로 설치한 flower는 site-packages 안에 있으므로 이 항목이 없다.(env.py:52)
6. ~/.claude/settings.json, 그다음 ~/.claude/settings.local.json의 env 블록 —— 마지막 폴백이며, 9개 인증 키만 가져온다.(env.py:56-75、:109-111)

어느 파일이 이기는가: 3번(프로젝트 .env)이 4번(전역 .env)을 이기고, 4번이 5번(저장소 루트 .env)을 이기며, 셋 다 6번(Claude Code 설정)을 이기고, 전부 1번(프로세스 환경)은 이기지 못한다.

구현 방식은 "이미 값이 있는 키는 덮지 않는다"이다(env.py:90-93): 앞에 놓인 것이 먼저 키를 차지하고, 뒤의 것은 빈 자리만 채운다. 그래서 우선순위는 파일 단위가 아니라 키 단위로 계산된다 —— 프로젝트 .env에 ANTHROPIC_BASE_URL만 써 두었다면, token은 전역 쪽에서 와도 된다. 같은 이름의 키는 처음 나타난 값이 끝까지 간다.

6번은 자동 탐색일 때만 활성화된다. 경로를 명시적으로 주면(load_dotenv("/path/to/.env")) 그 파일 하나만 읽고 어떤 폴백도 타지 않는다(env.py:86-87、:109).

6번: Claude Code의 token 빌려 쓰기¶

~/.claude/settings.json과 ~/.claude/settings.local.json을 차례로 읽어 data["env"] dict를 가져오고, 거기서 이 9개 키만 골라낸다(env.py:31-36、:65-74):

ANTHROPIC_API_KEY   ANTHROPIC_AUTH_TOKEN   ANTHROPIC_BASE_URL
ANTHROPIC_MODEL     ANTHROPIC_DEFAULT_OPUS_MODEL    ANTHROPIC_DEFAULT_SONNET_MODEL
ANTHROPIC_DEFAULT_HAIKU_MODEL    CLAUDE_CODE_SUBAGENT_MODEL    CLAUDE_CODE_EFFORT_LEVEL

파일이 없거나, 읽지 못하거나, 올바른 JSON이 아니면(OSError / ValueError) 빈 dict를 반환하고 계속 진행한다 —— 폴백이 실패했다고 이번 run까지 데려가서는 안 된다(env.py:62-63、:66-69).

코드가 취하는 입장은 이렇다: 빌리는 것은 "token을 어디서 찾을지"뿐이고, settings.json 안의 다른 어떤 것도(권한 규칙, hook, 모델 설정) 일절 넘겨받지 않는다. 그래서 이것은 setting_sources=[]의 portable 약속을 위반하지 않는다(env.py:17-19、:59-61). install.sh:77은 이를 하나의 기능으로 홍보한다: 로컬에 Claude Code를 설정해 둔 사람은 설정 화면조차 보지 않는다.

flower 不读 ~/.claude/settings.json —— 那是可移植性的代价。

.env 파싱 규칙¶

파싱 규칙은 외울 수 있을 만큼 짧다(env.py:95-107, 13줄): 줄마다 strip하고, 빈 줄과 #로 시작하는 줄, =가 없는 줄은 건너뛴다. 나머지는 첫 번째 =를 기준으로 key와 value로 자르고, 양쪽을 각각 strip한 뒤 value에 다시 .strip("'\"")를 한 번 더 건다 —— 앞뒤의 작은따옴표/큰따옴표는 무조건 벗겨내며, 짝이 맞을 필요도 없다.

인정하는 표기:

인정하지 않는 표기. 써도 에러는 나지 않고, 조용히 예상 밖의 값이 될 뿐이다:

빈 값도 키를 차지한다. 우선순위가 높은 파일에 ANTHROPIC_AUTH_TOKEN=가 나오면 take()가 os.environ["ANTHROPIC_AUTH_TOKEN"] = ""를 실행하고, 이후 파일들은 "키가 이미 존재함" 때문에 채워 넣지 못한다 (env.py:90-93). 반면 check_credentials()는 참 값으로 판정하므로 빈 문자열은 여전히 미설정으로 친다(env.py:186). 결과적으로 인증 정보도 없고 폴백도 못 받는다. 어떤 키를 원하지 않으면 줄 전체를 지워라. 빈 값으로 남기지 마라.

portable의 대가¶

build_options() 안의 그 한 줄이 전부다(agent.py:207):

"setting_sources": [] if portable else ["project"],

portable=True는 Runtime의 기본값이고, 커맨드라인에는 이걸 끌 스위치가 없다 —— 끄려면 Python API로 Runtime(portable=False)를 쓰는 수밖에 없으며, 그러면 ["project"]가 되어 프로젝트의 .claude/를 읽는다.

격리되는 것들¶

도메인 능력은 이 경로를 타지 않는다 —— 저장소와 함께 배포되며, plugins=[{"type": "local", "path": PLUGIN_DIR}]로 로드된다 (agent.py:26、:210-212). 배포를 보라. 도메인 지시는 Claude Code 기본 시스템 프롬프트 뒤에 append되는 것이지 교체가 아니다(agent.py:198-202). 그래서 전문화가 범용 능력의 손실을 대가로 하지 않는다.

다른 머신으로 옮길 때 챙길 것¶

• 인증 정보: 파일 하나. ~/.config/flower/.env를 복사해 가거나, 새 머신에서 다시 한 번 설정하면 된다. 가져가지 않으면 아무것도 돌지 않는다 —— 자동으로 상속되는 것은 없다.
• continuity 상태: 디렉터리 전체. runs/(session 저장소, manifest, lineage)와 .flower/(workbench).
• 단, 경로가 일치해야 한다. lineage.json에는 워크스페이스의 절대 경로가 저장되어 있고, 맞지 않으면 없는 것으로 치고 조용히 새 session으로 물러난다. 에러를 내지 않는다(lineage.py:65-66). 이유는 SDK의 project_key가 워크스페이스 경로에서 유도되기 때문이다 (/、_、.를 전부 -로 치환, runtime.py:40-41). 디렉터리 위치가 바뀌면 예전 session_id를 찾을 수 없다.

디스크 레이아웃¶

flower를 한 번 실행하면 두 개의 트리를 쓴다: <run_dir>/에는 장부와 session이, <workspace>/.flower/에는 workbench가 놓인다. 둘 다 기본적으로 현재 디렉터리 아래지만, 기준점이 다르다.

<run_dir>/ —— 기본값 ./runs/¶

runs/
  sessions.db        SQLite,全量 transcript(含每个 subagent 自己那条)
  manifest.json      运行清单:每一步的 session_id / 花费 / 重试 / 失败原因,跨进程累积
  lineage.json       血缘:步骤名 → session_id,同一个目录再跑一次靠它接上
  aside/             旁路问答的独立 Runtime,自己的 sessions.db + manifest.json
  workbench/         仅当走 run / once 路径且给了 -W

manifest.json의 각 행은 asdict(StepResult)에 두 개의 패치를 더한 것이다(runtime.py:44-71、:579-582):

디스크 기록 전략은 덮어쓰지 않고 이어 쓰기다: 매번 기록 전에 파일을 다시 읽어, run이 자기 것과 같은 행만 최신으로 바꾸고 남의 행은 그대로 둔다(runtime.py:564-586). 그래서 같은 디렉터리에서 flower를 여러 개 병렬로 돌려도 장부가 서로를 지우지 않는다.

runs/ 안의 것은 순수 데이터이며, 언제든 sqlite3나 tools/analyze_run.py로 오프라인에서 들춰볼 수 있다.

<workspace>/.flower/ —— workbench¶

.flower/
  INDEX.md      自动生成的索引,注入主 agent 的 system prompt
  scripts/      要跑第二次的脚本。首行 `# desc: 一句话` 会出现在索引里
  artifacts/    超过 2000 字符的长产出:报告、数据、日志
  notes/        跨步骤的决策记录
  spill/        落盘的大工具结果,文件名 = 内容 sha256 前 16 位 + `.txt`

세 개의 하위 디렉터리와 인덱스는 Workbench가 만든다(workbench.py:73-92). INDEX.md는 session 레벨의 system_prompt.append를 타므로 subagent는 상속받지 못한다 —— 따라서 "긴 산출물은 artifacts/에 쓴다"는 규칙은 coordinator가 task brief에서 다시 전달해야 하며, 그것이 유일한 통로다.

go 경로는 notes/ 아래에 다음을 고정적으로 생성한다:

--isolate일 때 workbench는 저장소 바깥으로 옮겨진다: <workspace 的父目录>/.flower-<workspace 名>/ (starter.py:47-55). worktree는 각 agent의 사설 사본이고 workbench는 agent를 가로지르는 공유 층이다. 공유되는 것을 사설 울타리 안에 넣을 수는 없다. 이때 모델에게 주는 경로는 절대 경로다(workbench.py:69-71、:142-145).

spill/에는 쓰는 주체가 둘이고, 낙점 알고리즘이 다르다:

기본 레이아웃에서는 같은 디렉터리다. 하지만 workbench가 옮겨지면(-W로 runs/workbench/에 떨어지거나, --isolate로 저장소 밖에 떨어질 때) 둘이 갈라진다 —— TrimPolicy 쪽은 항상 워크스페이스 안에 있는데, agent의 Read가 반드시 닿을 수 있어야 하기 때문이다.

spill_guard가 바꿔 넣는 것은 한 줄이 아니라, 한 줄짜리 포인터에 앞부분 400자를 더한 것이다(guard.py:132-140). spill 파일 자체를 읽는 호출은 통과시킨다. 그러지 않으면 "전문이 필요하면 Read로 읽어라"가 빈말이 된다 —— 읽어 오면 또 임계값을 넘고, 또 spill되어 무한 루프가 된다(guard.py:155-170).

sessions.db의 테이블 구조¶

테이블 세 개이며, 생성문은 stores/sqlite.py:27-51에 있다:

CREATE TABLE entries (
    store_key TEXT NOT NULL,
    seq       INTEGER NOT NULL,
    uid       TEXT,
    payload   TEXT NOT NULL,
    PRIMARY KEY (store_key, seq)
);
CREATE UNIQUE INDEX entries_uid
    ON entries(store_key, uid) WHERE uid IS NOT NULL;
CREATE TABLE meta (
    store_key TEXT PRIMARY KEY,
    mtime     INTEGER NOT NULL,
    next_seq  INTEGER NOT NULL
);
CREATE TABLE summaries (
    project_key TEXT NOT NULL,
    session_id  TEXT NOT NULL,
    mtime       INTEGER NOT NULL,
    data        TEXT NOT NULL,
    PRIMARY KEY (project_key, session_id)
);

store_key의 구성(sqlite.py:54-58): <project_key>/<session_id>이며, subagent는 뒤에 subpath 한 토막이 더 붙는다. project_key는 SDK가 워크스페이스 경로에서 유도한다 —— /、_、.를 전부 -로 바꾼다.

실제 샘플을 하나 보자(human-test/HT002/runs/sessions.db):

sqlite3 runs/sessions.db "select store_key, next_seq from meta;"

-Users-hechenyu-explore-test-ide/601c8c91-6c4b-4525-8a5f-295b99bf9515|37
-Users-hechenyu-explore-test-ide/47395075-bec7-466e-80cd-f4d60b360235|80
-Users-hechenyu-explore-test-ide/47395075-…/subagents/agent-a99a6ce30a5471f44|104

이 샘플은 entries 956건, meta 10건, summaries 4건이다 —— session 10건 중 4건이 메인 transcript, 6건이 subagent의 것이고, summaries는 정확히 메인 transcript 수와 같다.

session store 세 층¶

append(쓰기)는 언제나 전량을 디스크에 기록하며 한 글자도 고치지 않는다. 세 층은 load(모델에 다시 먹일 쪽)에만 영향을 준다. load의 실제 순서는 이렇다:

SqliteSessionStore.load     从 entries 表按 seq 读出全部
  → TrimmingSessionStore.expire()   时效性 Bash 结果 → 换成"已过期"
  → TrimmingSessionStore.trim()     旧的大 tool_result → 落盘 + 换成指针
    → PruningSessionStore.prune()   合成错误消息 / 旧的被拒调用 → 整条摘掉并重接链

2층은 trim이고 3층은 prune이다 —— trim은 크기와 가치로 버리고, prune은 "에러인지 여부"로 버린다. 헷갈리지 마라. 전체 시그니처는 Python API를 보라.

SqliteSessionStore —— 기반¶

SqliteSessionStore(path: str | Path)

외부 의존성 없는 SQLite 구현. Postgres / S3 / Redis로 바꾸려면 같은 프로토콜을 구현하면 되고, SDK에 딸린 일관성 테스트 스위트 claude_agent_sdk.testing.session_store_conformance로 바로 검증할 수 있다(sqlite.py:1-8).

프로토콜 메서드 외에, flower 자신이 쓰는 동기 조회가 세 개 있다:

TrimmingSessionStore + TrimPolicy / EphemeralPolicy¶

TrimmingSessionStore(path, workspace, policy: TrimPolicy | None = None,
                     ephemeral: EphemeralPolicy | None = None)

직교하는 두 규칙이다. TrimPolicy는 크기를 담당한다:

잘린 본문은 <sha256 前 16 位>.txt로 기록되고, 원래 자리는 [工具结果已归档:N 字符。完整内容在 <路径>,需要时用 Read 读取]로 대체된다(trim.py:54-57、:308-317).

EphemeralPolicy는 시효를 담당한다: git status、ls、ps 같은 결과는 아주 짧아서 크기 기준으로는 영원히 잘릴 차례가 오지 않지만, 그 정확성은 시간이 지나면서 감쇠한다 —— 20턴 전의 git status는 "쓸모없는" 게 아니라 오도한다.

Bash 도구의 결과에만 작용하며, 명령이 EPHEMERAL_CMD에 매치해야 한다. Read는 여기 포함되지 않는다: 파일 내용은 시간이 흐른다고 오도할 정도로 왜곡되지 않고, 오히려 모델 추론의 근거일 수 있다(trim.py:153-160). 만료된 내용은 spill하지 않는다 —— 만료된 git status를 아카이브해 봐야 의미가 없고, 다시 실행하면 얻어진다.

판단 함수는 is_ephemeral(cmd)이며, 이것은 동시에 coordinator에게 돌려주는 권한 목록이기도 하다: delegate_guard(allow_glance=True)가 같은 함수를 쓴다(trim.py:63-68、:128-150). 두 집합은 언제나 같아야 한다 —— 통과시키되 자르지 않으면 만료된 git status가 컨텍스트를 영구히 점유하고, 자르되 통과시키지 않으면 coordinator가 ls 하나 때문에 subagent를 파견해 4.3k의 기동 비용으로 수십 자를 바꾸게 된다. 화이트리스트에 명령을 하나 추가하는 것은 이 두 문장을 동시에 말하는 것과 같다.

언제 무엇을 쓰나:

• 단절 잔해만 컨텍스트에 안 들어가게 하고 싶다면 → 아무것도 할 필요 없다. Runtime의 기본값이 이미 PruningSessionStore다. trim=False는 큰 결과를 자르지 않을 뿐, prune은 그대로 한다.
• 장시간 실행이고 도구 출력이 크다면 → trim=True. go 경로의 CLI는 기본으로 켜져 있고, --no-trim으로 반대로 끈다.
• coordinator에 glance=True를 켰다면 → ephemeral은 반드시 켜 두어야 한다. 이유는 앞 문단 참고.

PruningSessionStore + PrunePolicy¶

PruningSessionStore(path, workspace, policy: TrimPolicy | None = None,
                    prune: PrunePolicy | None = None,
                    ephemeral: EphemeralPolicy | None = None)

keep_denials는 이 층까지 전달되는 유일한 Runtime 구성 파라미터다(Runtime(keep_denials=N)). 기본이 0이 아니라 1인 이유: 가장 최근의 거부는 유효한 신호이며, 모델이 같은 턴 안에서 차단된 명령을 반복 재시도하는 것을 막아준다. 키우지 마라 —— 거부된 호출은 애초에 실행된 적이 없어서 결과에 아무 정보도 없고, 실측상 한 건이 273자를 차지한다 (93자의 거부 문구 + 180자의 죽은 명령 원문). 게다가 오도한다: 실측에서 coordinator가 "Bash를 직접 쓰지 말라"를 몇 건 읽고 나면 허용된 git status조차 시도하지 않고 곧장 "Bash가 제한되어 있으니 agent를 파견해 보겠다"고 말한다(prune.py:135-148).

heal_orphans가 고치는 것은 중단 후 resume이 매번 400을 내는 문제다: 중단은 메시지 경계에서 끊기므로 당시 비행 중이던 tool_use 뒤에 tool_result가 아예 없을 수 있는데, API는 둘이 짝을 이루기를 요구한다. 이 망가진 히스토리는 transcript에 남아서 저절로 사라지지 않으며, 그래서 이후 모든 resume이 그것 때문에 되돌려진다. 고치는 방법은 고아를 포함한 그 assistant 항목 뒤에 user 항목을 하나 끼워 넣어 그 안의 모든 고아 결과를 한 번에 채우고, 원래 그 assistant를 가리키던 parentUuid를 새로 끼워 넣은 항목으로 돌리는 것이다 (prune.py:95-147). 보충하되 삭제하지 않는다: 고아를 삭제하면 부모-자식 체인을 다시 이어야 하고, 같은 assistant 항목 안에 정상 블록이나 텍스트, thinking이 함께 있을 수 있어 말려들기 쉽다(prune.py:195-204).

구조적 레드라인 세 가지. 어기면 API가 바로 에러를 낸다:

1. tool_result 블록 자체는 반드시 있어야 하며, content만 교체할 수 있다. 하나라도 빠지면 "Missing Tool Result Block"이다 (trim.py:20-22;prune.py:79-92).
2. isCompactSummary / isMeta 항목은 건드리면 안 된다 —— compact로 눌린 그 구간 히스토리의 유일한 존재 형태다 (trim.py:179-181).
3. 한 항목을 제거하면 그 자식을 그 부모에 반드시 다시 이어야 한다. transcript는 parentUuid 단일 체인이며, harness는 리프에서 거슬러 올라가므로 체인이 끊긴 지점 앞의 히스토리는 전부 사라진다(prune.py:95-122). 그래서 relink()는 제거 대상을 포함한 전체 리스트를 받아야 하고, 필터링은 자기가 한다.

SQLite 안의 원문은 한 글자도 고치지 않는다 —— 세 층은 "모델에 다시 먹이는 쪽"에만 영향을 준다(trim.py:18;prune.py:8).

네트워크 단절 resilience¶

long-horizon workflow는 한 번 돌면 몇 시간이고, 네트워크는 반드시 한 번은 끊긴다. 기본 동작은 아주 나쁘다: 끊기는 순간 harness가 transcript에 합성 assistant 메시지 하나를 밀어 넣는데(model="<synthetic>"、isApiErrorMessage=true), 본문은 API Error: Can't reach the API server …이다. 그것이 session의 리프가 되고, 이후 resume하면 "모델이 직전에 한 말"로 간주되어 다시 먹여져 모델은 자기가 네트워크 장애를 논하고 있다고 생각한다. 게다가 StepResult.text에 섞여 들어가 workflow를 따라 다음 step의 prompt로 전달된다(resilience.py:1-22).

resilience 층은 세 가지를 하며, 하나도 빠뜨릴 수 없다: 프로브, 처음부터가 아니라 이어 달리기, 에러를 컨텍스트에 넣지 않기.

Resilience 파라미터¶

백오프 공식(resilience.py:119-121):

min(base_delay * 2 ** (attempt - 1), max_delay) * (0.75 + random() * 0.5)

즉 ±25% 지터로, 네트워크가 복구되는 순간 여러 프로세스가 한꺼번에 몰려드는 것을 피한다. 기본값 기준: 1회차 백오프 4초(실제 3~5), 2회차 8초(6~10), 5회차부터는 120초로 상한(90~150).

프로브 전략¶

• 프로브 대상은 ANTHROPIC_BASE_URL의 host:port이지 api.anthropic.com이 아니다(resilience.py:67-72). 자체 게이트웨이를 쓸 때, 후자가 통한다고 전자가 통한다는 뜻은 아니다.
• DNS와 TCP 핸드셰이크만 한다: getaddrinfo 다음 connect_tcp, 그리고 곧바로 닫는다. HTTP를 보내지 않고, 인증 정보를 싣지 않고, 돈이 들지 않는다(resilience.py:75-85). 프로브는 반드시 공짜여야 한다. 그렇지 않으면 "단절 시 15초마다 프로브" 자체가 장애가 된다.
• 어떤 실패든 도달 불가로 친다 —— DNS가 죽었는지 TCP가 거부했는지 구분하지 않는다.
• wait_online()은 그 자리에서 기다린다: 통하면 True를 반환하고, max_offline_wait을 다 채우면 False를 반환한다. 처음 도달 불가일 때 <host>:<port> 不可达,等待恢复(最多 60 分钟) 한 줄을 알리고, 복구되면 다시 한 줄 <host>:<port> 恢复,继续를 알린다. 중간에는 화면을 도배하지 않는다(resilience.py:126-140).

시작 전의 그 인증 프로브는 별개다: 실제로 POST <BASE_URL>/v1/messages를 한 번 때리며, max_tokens=16, 기본 타임아웃 20초다(env.py:126-181). max_tokens를 1로 두지 마라 —— 실측상 사고 사슬을 강제하는 모델은 사고조차 담지 못해 서버가 30초까지 버둥거린 끝에 응답한다. 16으로 두면 3.6초면 된다(env.py:120-123).

에러 분류¶

classify(text)는 셋 중 하나를 반환한다. 치명적인 것부터 판정한다: 401 같은 텍스트에도 "connection" 같은 단어가 섞여 있는 경우가 흔해서, 순서가 뒤바뀌면 하염없이 기다리게 된다(resilience.py:53-64).

재시도 가능한 것과 불가능한 것을 구분하는 게 이 층의 핵심이다: 네트워크 흔들림은 기다려야 하고, 인증 오류는 즉시 멈춰야 한다 —— 단절 시 하염없이 기다리는 건 맞지만, key를 잘못 썼는데 하염없이 기다리는 건 시간을 태우는 짓이다.

무엇이 컨텍스트 밖에 막히는가¶

1. 합성 에러 메시지. PruningSessionStore가 load 시 통째로 제거하고 parentUuid를 다시 잇는다 (prune.py:27-32、:191-195). SQLite 안에는 그대로 남아 있고, 다시 먹이지 않을 뿐이다.
2. 이벤트 스트림에서 그것은 kind="text"가 아니라 kind="error"다. 그래서 StepResult.text에 들어가지 않고, workflow를 따라 다음 step의 prompt로 전달되지도 않는다(resilience.py:17-18).
3. resume_prompt는 의도적으로 어떤 에러 세부 정보도 담지 않는다. 모델은 "중단됐으니 이어서 하라"만 알면 되고, ENOTFOUND인지 503인지는 알 필요가 없다. 그건 로그의 몫이지 컨텍스트의 몫이 아니다(resilience.py:112-113). 로그는 manifest.json의 errors 필드에서 보라.

처음부터가 아니라 이어 달리기: 실패 시점에 session_id는 이미 확보되어 있으므로 resume으로 중단 지점에서 이어붙이며, 이전에 쓴 비용이 헛되지 않는다.

관련¶

• 커맨드라인 —— 각 스위치가 이 페이지의 설정에 어떻게 대응되는지.
• Python API —— Runtime, 세 개의 store, Resilience의 전체 시그니처.
• 배포 —— 컨테이너에서 실행하기, plugin으로 도메인 능력 배포하기.
• 용어집 —— 이 페이지에서 쓴 모든 단어의 정확한 의미.