evo-dispatch 워크그룹(workgroup) 규격 (초안 r1)

• 기반 규격: client-protocol.md v1. 이 문서는 그 위의 선택 확장이며 schema_version은 "1" 그대로다.
• 상태: 초안 r1 — 에서 서버를 구현했다. 클라이언트는 아직 없다.
• 근거: evo-cli의 dispatch-dev 요청(6c29ee93, 2026-11-03)과 evo-cli 사용자 결정(자동 처리는 그룹 안에서만, 그룹 관리는 dispatch 서버에 둔다).

1. 목표와 한계

같은 사용자의 활성 세션 여러 개를 워크그룹으로 묶어, 그룹 안에서만 메시지에 “자동 처리 허용” 표시(extensions.execution)를 쓸 수 있게 한다. 자동으로 처리할지는 받는 클라이언트가 정한다. 서버는 표시를 전달만 하고 실행하지 않는다.

• v1과 같이 같은 사용자 소유 세션끼리만 묶는다. 다른 사용자의 세션은 멤버로 넣을 수 없다.
• 멤버 자격은 만들 때 정해지고, 만든 뒤 멤버를 더 넣는 기능은 없다(v1 범위 밖). 구성을 바꾸려면 새 워크그룹을 만든다.
• 그룹 안 주소는 서버가 만든 별칭(wg- + 영문 소문자·숫자 4자, 예: wg-7k3f)만 쓴다. 사람이 고른 이름이 아니다.
• 그룹 메시지도 기존 사용자별 요청 수 한도(규격 §9, 기본 300/분)를 그대로 받는다. 별도 그룹 한도는 없다 — 같은 사용자 안이라 기존 한도로 무한 핑퐁을 충분히 막는다고 본다.
• 답장 체인 깊이는 extensions.execution.hop(0~20)으로 상한을 둔다. 증가는 클라이언트가 하고, 서버는 상한만 본다.
• 받는 쪽이 메시지를 자동으로 처리할지 판단하는 기준(표시가 있고, 보낸 이가 같은 그룹 멤버이며, E2E를 쓰면 서명이 확인됨)은 클라이언트 구현이다. 서버는 멤버 자격과 주소만 확인한다.

못 지키는 것(v1과 같음): 받은 메시지의 실행 여부·결과를 추적하지 않는다. 클라이언트가 무엇을 했는지는 다음 메시지(답장)로만 안다.

2. 멤버 자격

• dispatch_workgroup_create로 내 활성 세션들을 묶는다. 호출한 세션은 자동으로 들어가고, members에 다른 활성 세션(최대 15개, 그룹 전체 최대 16명)을 더 넣는다.
• 멤버가 아닌 세션(비활성, 다른 사용자)을 넣으면 no_active_recipient로 거부하고 그룹을 만들지 않는다.
• 서버는 멤버마다 그 그룹 안에서만 쓰는 별칭을 무작위로 정해 돌려준다. 같은 세션이 다른 그룹에 속하면 그룹마다 다른 별칭을 받을 수 있다.
• dispatch_workgroups로 내가 속한 그룹과 멤버(별칭·client_kind·session_id·device_id, 있으면 persona)를 본다. persona는 그 세션의 마지막 활성 신호가 알린 담당이다(client-protocol.md §2). 담당 없는 멤버는 필드가 없다. 서버는 담당으로 주소·권한을 가르지 않는다.
• dispatch_workgroup_leave로 내 세션만 그룹에서 뺀다. 멤버가 아니면 not_group_member다.
• 세션 교체(/clear·/compact, 규격 §5): message_recipient와 같은 방식으로, 같은 기기에서 이어지는 세션이면 멤버 자격이 새 session_id로 옮겨진다. 별칭은 바뀌지 않는다.
• 세션이 끝나거나(TTL·end) rotate 없이 사라지면 멤버 행은 남아 있지만 더 이상 활성 대상이 되지 않는다(아래 §3). 정리(삭제)는 범위 밖이며 후속 Issue에서 다룬다.

3. 주소

dispatch_send의 to.kind에 두 가지를 더한다.

to.kind	필수 값	받는 세션
workgroup	workgroup_id	그 워크그룹의 다른 활성 멤버 전부(보낸 세션 제외)
workgroup_member	workgroup_id, alias	그 별칭의 멤버 하나(활성일 때만)

• 보낸 세션이 그 workgroup_id의 멤버가 아니면 not_group_member(403)다.
• workgroup_member에서 별칭이 없거나, 그 멤버가 비활성이면 다른 주소 종류와 같게 no_active_recipient다(별칭이 있는지 알리지 않는다).
• 그룹의 다른 활성 멤버가 하나도 없으면(workgroup) no_active_recipient다.

4. 자동 처리 표시(extensions.execution)

"extensions": { "execution": { "auto": true, "workgroup_id": "<워크그룹 id>", "hop": 0 } }

필드	필수	내용
auto	필수	true면 “그룹 안 자동 처리 허용”을 뜻한다. false는 그룹 메시지이지만 자동 처리를 바라지 않는다는 뜻(사람 확인)
workgroup_id	필수	to.workgroup_id와 같아야 한다. 다르면 invalid_request
hop	선택(기본 0)	답장 체인 깊이. 자동 회신을 보낼 때마다 받은 값 + 1을 넣는다. 0~20, 넘으면 invalid_request

• extensions.execution은 to.kind가 workgroup·workgroup_member일 때만 쓸 수 있다. 다른 주소에 쓰면 invalid_request다.
• 서버는 멤버 자격과 모양만 검사한다. 자동 처리 여부의 최종 판단은 받는 클라이언트가 한다. 권고(evo-cli 쪽 설계):
  1. extensions.execution.auto가 true다.
  2. 보낸 이(from)가 같은 그룹의 멤버다(받는 쪽이 dispatch_workgroups로 확인).
  3. E2E(e2e.md)를 쓰는 메시지면 서명이 확인됐다(evo_e2e: verified).
  4. 위를 만족하지 않으면 사람에게 보여 주고 사람이 결정하게 한다(그룹 메시지라도 자동 처리하지 않는다).

5. 안전장치

• 속도: 그룹 메시지는 기존 사용자별 요청 수 한도(규격 §9)를 그대로 쓴다. 한도를 넘으면 rate_limited(429)다.
• 체인 깊이: hop이 20을 넘는 dispatch_send는 invalid_request다. 클라이언트는 자동 회신을 만들 때마다 hop을 올려야 하고, 상한에 닿으면 자동 회신을 멈추고 사람에게 알려야 한다(SHOULD).
• 그룹 메시지도 일반 메시지와 같은 보존·정리 규칙(규격 §7)을 따른다.

6. 서버 인터페이스

MCP tool 3종을 더한다(결과는 text 블록 하나, 과 같음).

tool	인자	결과
dispatch_workgroup_create	members: {client_kind, session_id} 배열(1~15개, 호출 세션은 자동으로 들어간다)	workgroup_id, my_alias, members(별칭·client_kind·session_id·device_id·self)
dispatch_workgroups	없음	workgroups: 내가 속한 그룹 목록(위와 같은 모양)
dispatch_workgroup_leave	workgroup_id	{workgroup_id, left: true}

오류 코드

기존 코드(규격 §9)에 다음을 더한다.

코드	HTTP	언제
not_group_member	403	to.kind가 workgroup·workgroup_member인데 보낸 세션이 그 워크그룹의 멤버가 아니다. dispatch_workgroup_leave를 멤버가 아닌 그룹에 불렀을 때도 같다

그 밖의 형식 오류(workgroup_id 없음·형식 틀림, 별칭 형식 틀림, extensions.execution을 다른 주소에 씀, hop 범위 밖)는 invalid_request다. 워크그룹이 없거나 내 것이 아니면 not_found다.

7. 시험 예시

examples/valid/message-workgroup-broadcast.json·message-workgroup-member-execution.json, examples/invalid/message-workgroup-missing-id.json·message-workgroup-bad-alias.json. 검증 방법은 규격 §11과 같다.

8. 미확인·미정

• 그룹 생성 뒤 멤버 추가·초대, 그룹 이름(사람이 보는 이름) — 필요해지면 후속 Issue.
• 멤버가 줄어 혼자 남은 그룹의 정리(삭제) — 세션·요청 정리와 같은 방식으로 후속 Issue에서 다룬다.
• 그룹 메시지의 E2E 수신자 계산(그룹 멤버의 기기 키를 한 번에 모으는 도움 tool) — 지금은 dispatch_workgroups로 멤버를 보고 dispatch_sessions로 공개키를 보는 두 호출로 할 수 있어 별도 tool을 더하지 않았다.