DEV Community

Cover image for osFoundry는 왜 Codex CLI에 변경을 푸시하지 않고 리소스마다 커서로 폴링하게 할까
BBT for BBT 한국어

Posted on

osFoundry는 왜 Codex CLI에 변경을 푸시하지 않고 리소스마다 커서로 폴링하게 할까

osFoundry MCP 서버에서 "뭔가 바뀌면 알고 싶은" 클라이언트가 쓸 수 있는 걸 이 Mac에서 토큰 없이 전부 두드려 봤다.

$ uv run --with tiktoken --with jsonschema python3 watch_sim.py
== Part 1: live wire, 8 calls each, ms ==
initialize                   HTTP 200  median  414.7  p90  757.8
tools/list                   HTTP 200  median  606.8  p90  716.7
resources/subscribe          HTTP 200  median  450.6  p90  550.2
GET (stream)                 HTTP 405  median  423.9  p90  475.4
tools/call poll (no token)   HTTP 401  median  322.0  p90  463.9
initialize capabilities: {"tools": {"listChanged": false}}
resources/subscribe -> {"code": -32601, "message": "Method not found"}
GET body -> ''
poll without token -> isError True | Authentication required
rate limit headers: limit 2000, reset in 61 s
Enter fullscreen mode Exit fullscreen mode

푸시 경로는 세 개 다 닫혀 있다. initialize가 선언하는 건 tools뿐이고 그마저 listChanged: false라서, 툴 목록이 바뀌어도 알려 주지 않는다. resources/subscribe는 "Method not found"다. Streamable HTTP 서버라면 서버→클라이언트 스트림을 열어 줄 MCP URL로의 GET은 405를 돌려준다. 남는 건 읽기 전용 툴 하나뿐이다.

{"name": "poll_resource_events",
 "description": "Resume from an event sequence for one granted channel, Note, knowledge base, record, or session.",
 "inputSchema": {"properties": {
     "resource_type": {"enum": ["message_channel", "note", "knowledge_base", "record_channel", "room",
                                "gitnest_repository", "agent_session", "team_session", "loop_session",
                                "graph_session"]},
     "resource_id": {"type": "string"},
     "after_sequence": {"type": "integer", "minimum": 0},
     "limit": {"type": "integer", "minimum": 1, "maximum": 100}},
   "required": ["resource_type", "resource_id"], "additionalProperties": false},
 "annotations": {"readOnlyHint": true, "openWorldHint": false, "destructiveHint": false},
 "securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:read"]}]}
Enter fullscreen mode Exit fullscreen mode

핵심은 "one granted"와 "resume from an event sequence" 두 표현이다. 이 글에서는 이 두 표현을 클라이언트 쪽을 Python으로 다시 만들어서 확인한다. 이 Mac에는 codex 바이너리가 없어서 클라이언트 역할은 스크립트가 했다. osFoundry 서버 코드는 공개돼 있지 않다. Part 1과 2는 라이브 서버고, Part 3은 재현이라 응답 모양과 활동 빈도는 재현 쪽에서 정한 값이다.

왜 푸시가 아니라 폴링일까, 특히 Codex라면

Codex CLI는 상주 프로세스가 아니다. 실행하면 돌고, 턴 하나를 처리하고, 끝나거나 사용자 입력을 기다린다. 푸시를 받으려면 세션과 세션 사이에도 누군가 귀를 열고 있어야 하는데, 노트북에선 대개 아무도 없다. 시퀀스 커서는 이런 생활 방식에 딱 맞는다. 클라이언트는 리소스마다 정수 하나만 들고 있다가, 내키는 때 돌아와서 그 뒤로 무슨 일이 있었는지 물으면 된다.

위의 ms 숫자는 일본에서 Apple M1으로 잰 거라 서버보다 경로 얘기에 가깝다. 더 중요한 건 레이트 리밋 헤더다. 인증 안 된 응답에 X-RateLimit-Limit: 2000이 붙고, 리셋은 61초쯤 뒤다. 로그인한 클라이언트도 같은 한도인지는 확인 안 했다. 그래도 리소스 30개를 30초마다 폴링해 봐야 분당 60요청이다. Codex로 변경을 지켜볼 때 발목을 잡는 건 서버 부하가 아니라 Codex 자신의 턴 수다. 폴링 한 번이 곧 모델이 툴을 부르고 결과를 읽는 한 턴이다.

폴링해도 되는 대상은 어떻게 찾을까

호출 두 개면 되고, 스키마만 봐도 설계 의도가 꽤 드러난다.

list_granted_resources   osfoundry:read  ro=True required=[] props=[]
list_project_resources   osfoundry:read  ro=True required=['project_id', 'resource_type'] props=['project_id', 'resource_type', 'search', 'offset', 'limit']
poll_resource_events     osfoundry:read  ro=True required=['resource_type', 'resource_id'] props=['resource_type', 'resource_id', 'after_sequence', 'limit']
59 tools on server; these three = 591 of 12662 tokens (4.7%, cl100k_base)
poll_resource_events types: 10 | list_project_resources types: 9 | only pollable: ['graph_session']
Enter fullscreen mode Exit fullscreen mode

list_granted_resources는 인자를 하나도 안 받고, 억지로 넣으면 스키마가 튕긴다.

list_granted_resources   no arguments           ok
list_granted_resources   project_id passed      REJECT additionalProperties
Enter fullscreen mode Exit fullscreen mode

클라이언트가 뭔가를 요청하는 툴이 아니라, 서버가 "네가 가진 건 이거다"라고 알려 주는 툴이다. initialize의 instructions도 "Use list_granted_resources first."로 시작한다. 돌아오는 건 연결에 추가된 프로젝트와 개별로 허용된 리소스다. 웹 클라이언트(ExternalAssistantsPanel.tsx)로 치면 Projects 영역과 "Older individual access" 영역이다.

list_project_resources는 resource_type이 필수다. "이 프로젝트 안에 있는 거 전부" 같은 목록은 없어서, 전체를 파악하려면 타입마다 한 번씩 아홉 번 불러야 한다. 한 타입에 50개가 넘으면(limit 최대 50, offset으로 페이지 넘김) 더 늘어난다. 설명문에는 프로젝트 단위 접근의 유일한 예외도 적혀 있다. "Ordinary Message channels require a separate invitation."

graph_session은 폴링은 되는데 목록에는 안 나온다. Graph는 오너의 데스크톱에 있고, 오너가 데스크톱 앱에서 공유한 다음에야 list_graph_sessions로 들어온다.

커서는 왜 서버가 아니라 클라이언트가 들고 있을까

osFoundry에는 두 방식이 다 있다. 에이전트 네트워크의 wait_for_messages는 커서를 서버가 들고 있어 준다. "Without after_sequence it resumes where your last call stopped"라고 돼 있고, timeout_s로 최대 50초까지 롱 폴링도 된다. poll_resource_events에는 둘 다 없다. timeout_s는 튕기고 설명엔 "resume from"뿐이니, 번호는 클라이언트가 챙겨 와야 한다.

wait_for_messages props: ['after_sequence', 'timeout_s', 'limit'] timeout_s max 50 | poll_resource_events has timeout: False
poll_resource_events     timeout_s 30           REJECT additionalProperties
Enter fullscreen mode Exit fullscreen mode

서버가 커서를 들고 있으면 듣는 쪽이 하나일 땐 편하다. 그런데 연결 하나를 클라이언트 둘이 같이 쓰면 깨진다. 같은 로그인으로 터미널 두 개에서 Codex를 열면 딱 그 상황이다. 재현에서 채널 이벤트 600개를, 랜덤하게 번갈아 폴링하는 터미널 두 개에 흘려 봤다.

two terminals, client cursor: A saw 600/600, B saw 600/600
two terminals, server cursor: A saw 305/600, B saw 295/600
Enter fullscreen mode Exit fullscreen mode

연결마다 서버가 커서를 하나 들고 있으면, 한쪽이 커서를 밀 때마다 다른 쪽은 그만큼 놓쳐서 각자 절반 정도만 본다. 요청에 after_sequence를 넣는 방식이면 둘 다 전부 보고, 서버는 읽는 쪽 상태를 하나도 안 들고 있어도 된다. 여러 툴이 제각각 읽어 가는 리소스 로그라면 커서 주인은 클라이언트가 맞다.

스키마상 after_sequence는 필수가 아니지만, 빼면 어떻게 되는지는 어디에도 안 적혀 있다. 거기 기대지 말자. 번호를 저장해 두고 매번 보내는 게 안전하다.

페이지가 꽉 차면 몇 번 불러야 할까

limit은 100이 끝이다. 대량 임포트 뒤라면 노트 하나에 이벤트가 수백 개 쌓여 있을 수 있다. 마지막 시퀀스부터 다시 부르고, 페이지가 꽉 차지 않은 채로 올 때까지 반복해서 비운다.

burst of 350 events, limit 100:  4 calls to drain, cursor ends at 350
burst of 350 events, limit  50:  7 calls to drain, cursor ends at 350
burst of 350 events, limit  20: 18 calls to drain, cursor ends at 350
Enter fullscreen mode Exit fullscreen mode

100으로 부르면 된다. 재현에서 응답 크기는 빈 페이지가 17토큰, 이벤트 하나짜리가 41토큰이었다(cl100k_base). 모양은 재현 쪽 거지 osFoundry 게 아니지만, 자릿수 감은 충분하다. 빈 폴링은 읽는 비용이 싸고, 폴링 비용은 거의 턴 수로 정해진다.

리소스 30개를 얼마 간격으로 폴링해야 할까

재현에서는 프로젝트 하나에 목록으로 뽑을 수 있는 아홉 타입의 리소스 30개를 두고 활동량을 한쪽으로 몰았다. 바쁜 게 3개(분당 이벤트 1개), 적당한 게 7개(10분에 1개), 조용한 게 20개(2시간에 1개). 빈도는 가정이다. 8시간짜리 하루를 시드 5개로, 가상 시계 위에서 돌렸다.

every 30 s, all 30                 calls/hour   3600  empty  94.7%  seen late median   14.9 s  p90   27.0 s  max     30 s  (1843 events/day)
every 5 min, all 30                calls/hour    360  empty  78.0%  seen late median  150.9 s  p90  271.1 s  max    300 s  (1843 events/day)
30 s, x2 when empty, cap 10 min    calls/hour    502  empty  70.2%  seen late median   34.9 s  p90  206.4 s  max    599 s  (1843 events/day)
30 s, x2 when empty, cap 30 min    calls/hour    420  empty  65.3%  seen late median   35.6 s  p90  238.4 s  max   1799 s  (1843 events/day)
server window for comparison: 2000 requests per ~61 s
Enter fullscreen mode Exit fullscreen mode

고정 30초는 빠르지만 95%가 헛방이다. 시간당 3,600번 부르고 거의 다 비어 있다. 고정 5분은 싸지만, 바쁜 채널까지 포함해서 전부 느리다. 리소스별 백오프(빈 폴링마다 그 리소스의 간격을 두 배로 늘리고, 이벤트가 오면 처음으로 되돌림)는 호출 수를 싼 쪽에 가깝게 맞추면서 지연 중앙값은 빠른 쪽에 가깝게 유지한다. 바쁜 리소스는 30초에 머물고 조용한 것만 멀어지기 때문이다. 대가는 상한값이다. 30분으로 두면 조용한 리소스의 첫 변경은 최대 30분까지 기다릴 수 있다.

Codex 입장에선 이 표가 오히려 타이머를 아예 안 돌릴 이유가 된다. 사람이 "뭐 바뀌었어?"라고 물을 때 저장해 둔 커서로 한 바퀴 돌면, 지켜보는 리소스 하나당 호출 한 번으로 그 시점까지의 변경을 지연 0으로 잡는다. 백오프 표는 Codex든 뭐든 계속 지켜보게 돌려 두는 스크립트를 위한 거다.

오너가 접근을 회수하면 어떻게 될까

오너가 4시간 07분 시점에 프로젝트를 뺐다고 하자. 커서 30개가 전부 이제 못 읽는 리소스를 가리킨다. 문제는 클라이언트가 그걸 언제까지 폴링하느냐다.

owner removes the project at 4 h 07 min (30 resources lose access):
  re-list grants every 10 min    failed polls after removal  180, list_granted_resources calls 25
  re-list grants every 60 min    failed polls after removal 3180, list_granted_resources calls 5
  re-list grants on first error  failed polls after removal    1, list_granted_resources calls 5
Enter fullscreen mode Exit fullscreen mode

타이머로 그랜트를 다시 확인하면 호출이 늘거나, 실패하는 폴링을 수천 번 쌓거나 둘 중 하나다. 처음 거절당한 순간을 "그랜트 다시 읽기" 신호로 쓰면 실패 한 번과 list_granted_resources 호출 한 번이면 끝난다. 그다음 목록에서 사라진 리소스의 커서를 버리면 된다. 나중에 오너가 프로젝트를 다시 넣어 주면 그 리소스들은 처음부터 새로 시작한다.

스키마는 어디서 막을까

나머지 케이스도 라이브 inputSchema에 jsonschema(Draft 2020-12)로 돌려 봤다.

list_project_resources   no resource_type       REJECT required
list_project_resources   limit 50               ok
list_project_resources   limit 51               REJECT maximum: limit
list_project_resources   graph_session          REJECT enum: resource_type
list_project_resources   search 101 chars       REJECT maxLength: search
poll_resource_events     no after_sequence      ok
poll_resource_events     graph_session          ok
poll_resource_events     after_sequence -1      REJECT minimum: after_sequence
poll_resource_events     limit 100              ok
poll_resource_events     limit 101              REJECT maximum: limit
poll_resource_events     resource_type project  REJECT enum: resource_type
Enter fullscreen mode Exit fullscreen mode

다들 제일 먼저 해 보는 게 resource_type: "project"다. 프로젝트는 로그를 가진 리소스가 아니라, 리소스를 보이게 해 주는 그랜트 단위다.

스크립트 전체는 M1에서 20.2초 걸렸고, 그중 대부분이 네트워크 호출 40번이었다. 유저 CPU 시간은 0.91초였다.

직접 만든다면

  • 로그는 리소스마다 하나로 두고, 커서는 클라이언트가 들게 한다. 연결 하나를 둘이 읽어도 이벤트를 뺏어 가지 않고, 서버는 읽는 쪽 상태를 저장할 필요가 없다.
  • 그랜트 목록은 인자 없는 전용 툴로 만들고, 클라이언트가 거기서 시작하게 한다. 찾을 수 있는 건 오너가 허용한 것뿐이어야 한다.
  • 페이지 크기에 상한을 두고, 다 비우는 법(마지막 시퀀스부터, 덜 찬 페이지가 올 때까지 다시 부르기)을 정해 둔다.
  • 백오프는 전역이 아니라 리소스별로. 바쁜 건 빠르게, 조용한 건 싸게.
  • 폴링이 처음 거절되면 그랜트를 다시 읽고, 사라진 커서는 재시도하지 말고 버린다.
  • 커서는 이벤트를 처리한 다음에 기록한다. 중간에 죽어도 건너뛰는 게 아니라 다시 읽게 된다.

연결마다 툴이 어떻게 정해지는지는 툴 스코프 페이지, 프로토콜의 짧은 정의는 MCP 용어 설명에 있다.

Top comments (0)