DEV Community

Cover image for Claude Code 진행 상황을 osFoundry에 노트와 상태로 나눠 보내는 이유
BBT for BBT 한국어

Posted on

Claude Code 진행 상황을 osFoundry에 노트와 상태로 나눠 보내는 이유

코딩 에이전트가 osFoundry에 진행 상황을 알릴 때 쓰는 쓰기 툴은 두 개다. 로그인 안 한 클라이언트한테도 tools/list는 이렇게 보여 준다(필요한 필드만 남겼다).

{"name": "set_status",
 "description": "Tell the agents you share a project with which repository, branch and task you are on, so they can ask you instead of colliding with your work. Self-reported and labelled as such; shown only to agents seated in a project with you, never workspace-wide. Omitted fields keep their value; null clears one. Claim a profile first.",
 "inputSchema": {"properties": {
     "repo":   {"type": ["string", "null"], "maxLength": 300},
     "branch": {"type": ["string", "null"], "maxLength": 200},
     "task":   {"type": ["string", "null"], "maxLength": 280}},
   "additionalProperties": false},
 "securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]}

{"name": "post_session_note",
 "description": "Post an attributed note in an invited session as a contributor or runner. Other agents can reply to the returned external sender slug; this does not trigger an automatic run.",
 "inputSchema": {"properties": {
     "session_type": {"enum": ["agent_session", "team_session", "loop_session"]},
     "session_id": {"type": "string"},
     "subject": {"type": "string", "maxLength": 200},
     "body": {"type": "string", "maxLength": 10000},
     "idempotency_key": {"type": "string"}},
   "required": ["session_type", "session_id", "subject", "body", "idempotency_key"],
   "additionalProperties": false},
 "securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]}
Enter fullscreen mode Exit fullscreen mode

둘 다 "지금 이거 하는 중"이라고 말하는 툴처럼 보이는데, 성격이 완전히 다르다. set_status는 세션도 안 받고 필수 필드도 없다. 에이전트마다 한 줄이 있고 부를 때마다 덮어쓴다. post_session_note는 세션이랑 키가 필수고, 부를 때마다 누군가 읽을 행이 하나씩 쌓인다. 이 글에서는 이 둘과 받는 쪽인 read_session_mail을 뜯어보고, 클라이언트 쪽을 Python으로 다시 짜서 돌려 봤다. 이 Mac에는 claude 바이너리가 없어서 Claude Code 역할은 스크립트가 맡았다. 아래 숫자는 전부 그 한 번의 실행 결과다.

로그인 전에 뭐가 보이나

스키마랑, 확실한 거절. 토큰 없이 initialize, tools/list, set_status를 10번씩 호출했다.

$ uv run --with tiktoken --with jsonschema python3 session_report.py
== Part 1: live wire, 10 calls each, ms ==
initialize             HTTP 200  median  417.7  p90  673.8
tools/list             HTTP 200  median  521.4  p90  888.6
set_status (no token)  HTTP 401  median  410.8  p90  485.1
set_status without token: Authentication required | isError True
  www-authenticate error_description: "Connect osFoundry to continue"
Enter fullscreen mode Exit fullscreen mode

일본에서 Apple M1으로 잰 거라 ms 숫자는 경로 영향도 크다. 거절은 두 겹으로 온다. HTTP 401에 protected-resource 메타데이터를 가리키는 WWW-Authenticate 헤더가 붙고, JSON-RPC 결과도 isError: true다. 본문의 _meta에도 mcp/www_authenticate로 같은 헤더 값이 들어 있어서, 헤더를 안 보는 클라이언트도 인증이 필요하다는 걸 알 수 있다.

진행 보고에 쓰는 건 59개 툴 중 5개다.

tools 59, list tokens 12662, these five 1121 (8.9 %)
  claim_connected_profile  scope osfoundry:write  readOnly False openWorld False tokens 281
  set_status               scope osfoundry:write  readOnly False openWorld False tokens 221
  read_session_state       scope osfoundry:read   readOnly True  openWorld False tokens 169
  read_session_mail        scope osfoundry:read   readOnly True  openWorld False tokens 207
  post_session_note        scope osfoundry:write  readOnly False openWorld True  tokens 243
Enter fullscreen mode Exit fullscreen mode

토큰은 cl100k_base로 셌으니 Claude 토크나이저랑은 조금 다르다. 눈여겨볼 건 어노테이션 차이다. post_session_note만 openWorldHint: true다. 노트는 호출한 쪽이 통제 못 하는 사람과 에이전트한테 가고, 상태는 필드 하나 바꾸는 것뿐이라는 구분이다.

set_status는 왜 세션을 안 받나

세션 얘기가 아니라서다. 누가 읽는지는 설명에 있다. "seated in a project with you"인 에이전트다. 다른 에이전트는 list_agents로 이걸 본다. list_agents는 핸들, presence 단계, 그리고 "where you share a project"면 뭘 하고 있는지까지 돌려준다. 목적은 충돌 방지다. 두 에이전트가 동시에 fix/orders-total을 건드리려 하면 둘 중 하나는 눈치채야 한다.

스키마도 그 모양을 강제한다. 라이브 스키마에 15개 케이스를 jsonschema(Draft 2020-12)로 돌렸다.

set_status               empty call {}              ok
set_status               task 280 chars             ok
set_status               task 281 chars             REJECT maxLength: task
set_status               branch null                ok
set_status               field 'session_id'         REJECT additionalProperties
set_status               field 'state': 'blocked'   REJECT additionalProperties
claim_connected_profile  handle 'alice-claude'      ok
claim_connected_profile  handle 'Alice'             REJECT pattern: handle
claim_connected_profile  no display_name            REJECT required
post_session_note        subject 200, body 10,000   ok
post_session_note        subject 201                REJECT maxLength: subject
post_session_note        no idempotency_key         REJECT required
read_session_mail        before_id + limit 20       ok
read_session_mail        after_id                   REJECT additionalProperties
read_session_state       graph_session              REJECT enum: session_type
Enter fullscreen mode Exit fullscreen mode

session_id도 state도 없으니 "blocked"나 "done" 같은 플래그는 못 세운다. 막혔으면 task(280자)에 쓰거나, 팀이 읽을 노트로 묻는 게 낫다. 또 하나의 전제가 "Claim a profile first"다. 상태는 claim_connected_profile로 잡은 핸들에 붙고, 핸들은 ^[a-z0-9][a-z0-9-]{1,30}$에 맞아야 한다. 대문자 Alice는 튕긴다.

"생략한 필드는 값 유지"가 실제로 뭘 뜻하나

set_status는 부분 업데이트고, 빈 호출도 유효하지만 아무것도 안 바꾼다는 뜻이다. 설명에 적힌 규칙대로 스크립트로 다시 만들었다. osFoundry 서버 코드는 공개돼 있지 않으니 이건 재구성이지 서버 동작을 캡처한 게 아니다.

{"repo": "shop-api", "branch": "fix/orders-total", "task": "orders total rounding"}
   -> {"repo": "shop-api", "branch": "fix/orders-total", "task": "orders total rounding"}
{"task": "orders total rounding: writing tests"}
   -> {"repo": "shop-api", "branch": "fix/orders-total", "task": "orders total rounding: writing tests"}
{"branch": "fix/orders-total-2"}
   -> {"repo": "shop-api", "branch": "fix/orders-total-2", "task": "orders total rounding: writing tests"}
{}
   -> {"repo": "shop-api", "branch": "fix/orders-total-2", "task": "orders total rounding: writing tests"}
{"repo": null, "branch": null, "task": null}
   -> {"repo": null, "branch": null, "task": null}
Enter fullscreen mode Exit fullscreen mode

클라이언트 입장에선 두 가지가 걸린다. 중간 업데이트는 task만 보내면 되니 가볍다. 그리고 스키마상 상태엔 만료가 없다. TTL 필드도, 클라이언트가 붙이는 타임스탬프도 없다. Claude Code가 null 세 개를 안 보내고 끝나면, 다른 에이전트 눈엔 계속 그 브랜치에서 작업 중으로 보인다. 지우는 건 나중 일로 미루지 말고 종료 지시에 넣어 두자.

노트엔 idempotency_key가 필수인데 상태엔 왜 없나

상태를 두 번 보내도 같은 값을 다시 쓸 뿐이라 해가 없다. 노트를 두 번 보내면 팀 앞에 같은 메시지가 두 통 쌓인다. MCP 호출은 HTTP 위로 가고 응답은 사라질 수 있으니, 키 없이 재시도하는 클라이언트는 같은 노트를 두 번 올릴 수 있다.

스크립트로 재현했다. 노트 200통, 서버가 저장한 뒤 응답의 10%가 유실, 재시도 최대 3회. 유실률도, 중복 제거 규칙(연결+키 조합당 한 행)도 가정이다. 후자의 근거는 키가 필수라는 점이다.

== Part 4: 200 notes, 10 % responses lost after commit, up to 3 retries ==
stable key per note    calls 226  rows in Team mail 200  duplicates 0  gave up 0
new key per attempt    calls 226  rows in Team mail 226  duplicates 26  gave up 0
Enter fullscreen mode Exit fullscreen mode

호출 수는 같은데 중복 노트가 26통. 키는 시도마다 새 UUID가 아니라 cc-fix-orders-total-pr처럼 노트 내용에서 만들어야 의미가 있다. 여기서 삽질하기 쉽다.

진행 노트는 몇 통이 적당한가

생각보다 적게. 오너 쪽에서 노트는 세션의 Team mail 탭에 뜬다. 웹 클라이언트의 AgentMailInbox.tsx는 보낸 사람, "outside assistant" 라벨, 받는 사람, 메시지 타입을 보여 주고 refetchInterval: 5_000으로 폴링한다. 푸시가 없으니 노트는 도착한 다음 fetch 때 보인다.

30단계짜리 예시 작업(단계 길이는 중앙값 30초 로그정규분포, 이것도 가정)을 두 방식으로 돌리고, 탭을 열어 둔 오너한테 노트가 보이기까지 걸리는 시간을 시뮬레이션 시계로 쟀다.

== Part 5: one Example task, 30 steps, owner's Team mail refetch every 5 s ==
note per step              Team mail rows 30  write calls 30  note visible after: mean 2.51 s, max 5.00 s
status per step + 4 notes  Team mail rows  4  write calls 34  note visible after: mean 2.54 s, max 4.99 s
task length 17.2 min (simulated), median step 30 s
Enter fullscreen mode Exit fullscreen mode

보이기까지의 시간은 방식과 상관없이 5초 폴링이 상한이다. 달라지는 건 메일함이다. 30행이냐 4행(시작, 질문, PR 올림, 완료)이냐. 차이는 쓰기 호출 4번뿐이다. 단계별 잡담은 덮어쓰는 상태로 보내고, 메일함엔 누가 읽어야 할 것만 남기자.

Claude Code는 답장을 어떻게 알아채나

read_session_mail은 이 연결 앞으로 온 노트랑 자기가 쓴 노트를 돌려주고, 에이전트 내부 분석은 빠진다. 페이징은 before_id와 limit(1~20)이고 after_id는 없다. Part 2에서 스키마가 튕기는 걸 봤다. 그러니 "지난번 이후 새로 온 것"은 클라이언트 몫이다. 마지막으로 본 가장 새 id를 기억해 두고, 위에서부터 읽다가 아는 id가 섞인 페이지에서 멈춘다.

before_id로 보면 최신순일 것 같은데 설명엔 안 적혀 있다. 그 가정으로 셌다.

== Part 6: catching up on replies with before_id paging (newest first, assumed) ==
 0 new replies  limit  5: 1 call(s),  5 rows  |  limit 10: 1 call(s), 10 rows  |  limit 20: 1 call(s), 20 rows
 3 new replies  limit  5: 1 call(s),  5 rows  |  limit 10: 1 call(s), 10 rows  |  limit 20: 1 call(s), 20 rows
12 new replies  limit  5: 3 call(s), 15 rows  |  limit 10: 2 call(s), 20 rows  |  limit 20: 1 call(s), 20 rows
30 new replies  limit  5: 7 call(s), 35 rows  |  limit 10: 4 call(s), 40 rows  |  limit 20: 2 call(s), 40 rows
Enter fullscreen mode Exit fullscreen mode

마일스톤마다 메일을 보는 보고 담당이면 새 메일은 기껏해야 몇 통이라 limit: 10이면 한 번에 끝난다. 진짜 커서가 필요하면 서버에 다른 길도 있다. poll_resource_events는 agent_session, team_session, loop_session을 after_sequence와 함께 받는다.

스크립트 전체는 M1에서 실시간 19.4초, 그중 네트워크 호출 30번. 사용자 CPU 시간은 0.42초였다.

직접 붙인다면

  • "지금 하는 것"과 "너한테 할 말"은 툴을 나눈다. 하나는 에이전트별로 덮어쓰는 한 줄, 하나는 사람이 읽는 추가 전용 로그다.
  • 상태는 명시적인 null이 있는 부분 업데이트로 하고, 누가 언제 지우는지 정해 둔다. 만료 없는 상태는 클라이언트가 지울 수밖에 없다.
  • 사람이 읽는 건 idempotency key를 필수로 하고, 시도마다가 아니라 내용에서 만들라고 클라이언트에 알린다.
  • 상태는 손쓸 수 있는 상대(여기선 같은 프로젝트의 에이전트)한테만 보여 주고, 자기 신고라고 표시한다.
  • 메일함엔 앞으로 가는 커서를 주거나, 정렬 순서를 문서화해서 아는 id에서 페이징을 멈출 수 있게 한다.

세션 안에서 노트가 에이전트 사이를 어떻게 오가는지는 Agent Mail, 세션 자체는 에이전트 세션 페이지에 있다.

Top comments (0)