tmpl/multi-agent-mux

Fork 0

Files

T

Godopu d1efce2971 chore(release): bump skills and framework version to v2.2.1

2026-08-24 15:13:46 +09:00

19 KiB

Raw Permalink Blame History

📜 Multi-Agent Mux 버전 이력 (`VERSIONS.md`)

이 문서는 multi-agent-mux 프레임워크의 버전별 주요 기능 추가, 아키텍처 개선, 버그 수정 및 품질 검증 이력을 기록합니다.

📌 현재 버전 개요 (Current Release)

프레임워크 버전: v2.2.1
최신 릴리스 일시: 2026-08-24 (KST)
기준 브랜치: main
핵심 아키텍처:
- Single-Workspace 2xK Multi-Pane Tiling Optimization: 기본 최소 페인 너비 완화(MAM_MIN_PANE_COLS=40)로 80~~100컬럼 창에서 3~~4개 에이전트 단일 워크스페이스 타일링 보장
- --herdr-workspace Option & Runtime Label Sync: Herdr 세션 내 워크스페이스 라벨 독립 지정 및 런타임/YAML 실시간 동기화
- Legacy Fallback Chain Decoupling: 데몬 소켓(herdr_session)과 워크스페이스 라벨(herdr_workspace) 조회 체인 원천 분리
- Modern Agent Adapter & TUI Readiness: 최신 Claude Code(v2.1.241) 배너 및 4대 에이전트 TUI 초고속 감지
- 2xK Right-Growth Grid Layout Engine (B-20): 동적 터미널 감지 및 2xK 우측 확장 타일링 엔진
- Universal Herdr Session Isolation: 단일 Herdr 서버 컨텍스트 기반 세션 격리
- Tier-1 Fast-Path Lifecycle: 0ms 지연의 대화 UUID 캡처 및 초고속 재개(Resume)

🧭 스킬 패키지 버전 매트릭스 (Skills Version Matrix)

모든 8개 스킬은 YAML frontmatter 메타데이터(author, version, platforms, environments) 표준화를 통해 v2.2.1으로 동기화되어 배포됩니다.

스킬명	버전	역할 및 주요 책임	상태
`multi-agent-mux-create`	`2.2.1`	에이전트 세션 신규 생성 및 Herdr 컨테이너 격리 스폰	✅ 배포
`multi-agent-mux-stop`	`2.2.1`	대화 UUID 원자적 캡처 및 세션 안전 종료 (Graceful Stop)	✅ 배포
`multi-agent-mux-resume`	`2.2.1`	온디스크 대화 컨텍스트 기반 Tier-1 초고속 세션 복원	✅ 배포
`multi-agent-mux-status`	`2.2.1`	실시간 Herdr 세션 및 레지스트리 드리프트 스냅샷 조회	✅ 배포
`multi-agent-mux-monitor`	`2.2.1`	YAML ↔ 런타임 상태 간 자율 조정자 (Reconciler Loop)	✅ 배포
`multi-agent-mux-delegate-job`	`2.2.1`	MQTT 이벤트 채널 기반 비동기 단위 작업 위임	✅ 배포
`multi-agent-mux-loop`	`2.2.1`	Planner-Creator-Reviewer 3자 자율 계획·실행·피어리뷰 루프	✅ 배포
`multi-agent-mux-orc-onboard`	`2.2.1`	오케스트레이터 UUID 격리 등록 및 서브 세션 오염 방지	✅ 배포

📋 버전별 상세 변경 내역 (Changelog)

🚀 `v2.2.1` — Single-Workspace 2xK Multi-Pane Tiling Optimization & Premature Overflow Fix (2026-08-24)

주요 마일스톤: MAM_MIN_PANE_COLS 기본값 60→40 완화, 표준 80~100컬럼 터미널 뷰포트에서 조기 워크스페이스 오버플로(가상 데스크톱 분리) 방지 및 단일 워크스페이스 2x2 통합 타일링 완성, 신규 80/79 경계 및 90/100 col 타일링 테스트 6종 추가, 다중 에이전트 피어 리뷰 100% PASS 달성.

1. 2xK 레이아웃 엔진 최소 폭 완화 (`lib_py/layout.py`, `lib.sh`)

compute_2xk_layout 기본 min_cols 및 CLI --min-cols, lib.sh:432의 ${MAM_MIN_PANE_COLS:-40}, .mam.env.example 문서를 40으로 4중 일치화.
90~100컬럼 너비 터미널에서 3번째, 4번째 에이전트 생성 시 불필요하게 가상 데스크톱(Workspace)이 분리되던 현상 완전 해소.

2. 경계값 및 타일링 자동화 테스트 확충 (`tests/test_layout.py`, `tests/test_tier1_unit.py`)

80 컬럼(분할 성공) vs 79 컬럼(오버플로) 하한 경계값 검증.
90 및 100 컬럼 단일 워크스페이스 1→2→3→4 단계 2x2 타일링 및 5번째 에이전트 오버플로 전 과정 수명 주기 검증.

🚀 `v2.2.0` — Herdr Workspace Label Standardization, Runtime Sync & Legacy Fallback Decoupling (2026-08-24)

주요 마일스톤: --herdr-workspace 옵션 전 스킬 도입 및 YAML 독립 직렬화, Herdr 런타임 워크스페이스 레이블 실시간 동기화, 레거시 소켓 폴백 체인 분리(Breaking Change 방어), 최신 Claude Code TUI 감지 토큰 반영, 27개 신규 테스트 추가 및 만장일치 PASS 달성.

1. `--herdr-workspace` 옵션 도입 및 Herdr 런타임 레이블 동기화

CLI 옵션 및 YAML 직렬화 표준화:
- create_session.sh, resume_session.sh, update_yaml_resumed.sh, stop_session.sh에 --herdr-workspace <name> 파서 및 환경변수(HERDR_WORKSPACE) 지원 추가.
- agent-sessions.yaml에 herdr_session(소켓명)과 herdr_workspace(워크스페이스 라벨)를 각각 독립 필드로 영구 직렬화.
Herdr 런타임 워크스페이스 레이블 실시간 연동 (lib.sh, resume_session.sh):
- herdr workspace create 호출 시 --label "$MAM_WS_LABEL" 전달 및 기존 워크스페이스 사용 시 herdr workspace rename 자동 호출.
- resume_session.sh 실행 시 저장된 herdr_workspace를 읽어 Herdr 런타임 레이블 복원 보장.

2. 레거시 소켓 폴백 체인 분리 및 Breaking Change 원천 차단

소켓 vs 워크스페이스 함수 완전 분리 (lib.sh):
- resolve_herdr_session(): 데몬/소켓 세션명만 반환 (row herdr_session -> row herdr_server -> env -> slug).
- resolve_herdr_workspace(): 워크스페이스 라벨만 반환 (row herdr_workspace -> pane.cwd slug -> caller ws arg).
- 기존 코드베이스 6개 지점(lib.sh:1027, reconcile.sh:135, 399, 495, status.sh:145, 270)에서 소켓 검색 시 herdr_workspace를 오인 참조하던 구문을 완전히 제거.
외부 세션 입양(Drift-B) 보강 (reconcile.sh):
- 외부 세션 입양 시 herdr_workspace와 herdr_server를 자동 채번 및 직렬화.

3. 최신 에이전트 TUI 준비 감지 보강 (`claude.py`, `lib.sh`)

최신 Claude Code(v2.1.241)의 시작 배너(Claude Code, Opus 5 with high effort 등)를 ready_tokens에 추가하여 세션 생성 타임아웃 방지.

🚀 `v2.1.0` — 2xK Grid Layout Engine, Explicit Agent Standardization & Herdr Session Hardening (2026-08-24)

주요 마일스톤: 2xK 우측 성장 그리드 레이아웃 엔진(lib_py.layout) 구축(B-20), 전 스크립트 --agent / --herdr-session 표준화 및 전파 가드, 전체 346개 테스트 스위트 100% PASS 달성.

1. 2xK 우측 성장 그리드 레이아웃 엔진 구축 (B-20 / I-2, I-3, C-1, J-1)

순수 파이썬 레이아웃 엔진 신설 (lib_py/layout.py):
- tput 기반 터미널 크기 동적 감지 및 2xK(2행 고정, 우측 열 추가) 그리드 기하학 계산 엔진 구현.
- 패널 번호 순서(0:좌상, 1:좌하, 2:중상, 3:중하...)에 따른 우측 확장 타일링 분할 명령(split-pane -h/-v, select-pane) 계산.
- 헤드리스/CI 최소 차원(최소 너비 60, 최소 높이 20) 가드 및 default=60 falsy-zero trap 해결 (_env_int).
33개 신규 레이아웃 단위/회귀 테스트 구축 (tests/test_layout.py):
- 1~8개 패널 수식 검증, 비정상 인자/환경변수 방어, 무한 루프 방지 가드 검증.

2. 에이전트 인자 표준화 및 레지스트리 자동 추론

stop_session.sh, create_session.sh, resume_session.sh, update_yaml_resumed.sh, resolve_session_id.sh 전반에 걸쳐 --agent <claude|agy|hermes|cline> 명시적 표준화.
미지정 시 YAML 레지스트리(agent-sessions.yaml) 기반 에이전트 타입 자동 추론(resolve_agent_type_from_registry) 연동.

3. `--herdr-session` 격리 세션 옵션 표준화 및 전파 가드

create_session.sh, resume_session.sh, stop_session.sh, update_yaml_resumed.sh 전반에 --herdr-session <NAME> 표준 옵션화 (레거시 --herdr-server 완전 호환).
create_session.sh에서 명시적 세션명이 워크스페이스 슬러그에 의해 덮어씌워지지 않도록 가드 보강.
resume_session.sh의 post-spawn 재개 시 신규 Herdr 세션명이 YAML 레지스트리에 정확히 전파되도록 갱신 로직 및 신규 Tier 2 테스트 5건 추가.

4. 테스트 스위트 확장 및 피어 리뷰 전원 만장일치 PASS

전체 테스트 스위트 수 276건 → 346건 (100% PASS) 확장.
Multi-Agent Loop를 통한 Reviewer(claude, cline) 전원 [VERDICT: PASS] 검증 완료.

🚀 `v2.0.0` — Unified Agent Adapter Architecture & Herdr Standardization (2026-08-17)

주요 마일스톤: 에이전트 지식 계층 단일 소스화(A-4), 레거시 격리 완전 폐기(Option B), 셸 브리지 하드닝 및 스킬 메타데이터 규격화 완료.

1. 에이전트 지식 계층 마이그레이션 (A-4 Phase 2 / P3-1)

BaseAgentAdapter 추상 클래스 및 4대 어댑터 구축:
- .agents/skills/lib_py/agents/base.py: DiscoveryContext 및 추상 인터페이스 정의 (ready_tokens, exit_key, delegate_agent_key, identity_cache_fields, artifact_path, verify_artifact, purge_artifacts, spawn_spec, resume_spec, auth_ok, discover).
- .agents/skills/lib_py/agents/adapters/: ClaudeAgentAdapter, AgyAgentAdapter, HermesAgentAdapter, ClineAgentAdapter 4개 구체 클래스 구현.
facts 브리지 셸 인터페이스 하드닝:
- lib_py.agents CLI 모듈을 통해 8개 MAM_* 변수를 shlex.quote 안전 인용 처리하여 방출.
- wait_for_tui_ready 빈 토큰 시 전량 매칭 오탐 방지 및 미지 에이전트 fail-closed 가드 내장.
셸 스크립트 전반 어댑터 이관:
- create_session.sh, resume_session.sh, stop_session.sh, reconcile.sh에 산재되어 있던 40여 개 하드코딩 분기를 어댑터 호출로 일원화.

2. 레거시 `isolation.root` 및 C-3b 소비자 완전 폐기 (Option B)

Universal Global Config 전환 이후 남아있던 4개 레거시 격리 소비자 코드(lib.sh::mam_session_iso_root, workspace_uuid.py::iso_root_of, verify_session.py, stop_session.sh) 및 atomic_yaml.py의 레거시 유효성 검사 절 100% 삭제.
저장소 내 격리 잔재 참조 0건 달성.

3. 셸 브리지 보안 및 예외 처리 강화 (R1, R2, N1 교정)

R1 (위임 에이전트 키 폴백 보강): 브리지 미작동 시 delegate_agent가 antigravity-cli로 일괄 퇴화하지 않고 claude-code, hermes-agent, cline-agent로 명시적 case 폴백하도록 개선.
R2 (argv 서브커맨드 전환): python -c 셸 변수 문자열 보간을 spawn-spec, resume-spec, exit-key 서브커맨드로 전면 전환하여 공백/작은따옴표 경로 에러 및 코드 주입 위협 원천 차단.
N1 (클린 환경 격리 가드): test_a4_adapter_contract.py 내 CLI 테스트가 앰비언트 PYTHONPATH 없이도 독립 통과하도록 환경 격리 보강.

4. 스킬 메타데이터 규격화 및 피어 리뷰 100% PASS

8개 SKILL.md frontmatter version: 2.0.0 통일 및 배포 무결성 검증.
Reviewer cline (Job e7b9812b) 및 Planner/Senior Reviewer claude (Job 31730364) 전원 [VERDICT: PASS] 획득.

5. 레거시 주석 및 사용법 정합성 최신화 (C-6)

stop_session.sh 상단 주석 및 usage() 내 폐기된 플래그(--mode soft|hard, --capture-id, --graceful) 안내 문구를 완전 제거하고 현행 4대 에이전트(claude, agy, hermes, cline) 및 플래그 체계로 동기화.
회귀 방지 컴포넌트 테스트(test_comp_stop_usage_matches_parser) 신설.
회귀 및 계약 테스트: 263/263 PASS (100%) 달성.

6. macOS NFS 감지 `df -P` 폴백 검증 및 종결 (B-5)

_check_is_nfs(lib.sh)의 macOS/BSD 환경 내 GNU 전용 df --output 구문 오류 시 POSIX df -P 폴백 동작을 실측 및 단위 테스트(test_stop_check_is_nfs_local)로 검증 완료하여 B-5 이슈를 정식 종결.

7. `agent_identities` tier-3 신원 캐시 완전 제거 및 UUID 해결 경로 PyYAML 탈의존 (B-10 / Option A)

쓰기 경로가 존재하지 않아 구조적으로 히트 불가였던 tier-3 폴백과 부속 소비자(workspace_uuid.py, reconcile.sh drift D, stop_session.sh 캐시 소거)를 전면 삭제.
UUID 해결 경로를 tier-1(per-row own id) → tier-2(어댑터 discover()) 2단계로 단순화.
verify_session.py::mam_orchestrator_uuids 의 즉시 yaml import 를 YAML 폴백 분기로 이동, UUID 해결 경로가 PyYAML 없이 완주함을 실행 가드로 고정(atomic_yaml.py 의 시스템 PyYAML 요구는 설계상 유지).
회귀 가드 3종 신설 — 읽기 경로 부활 차단, import yaml AST 검사(지연 import 포함), 실행 경로 검증.
회귀 및 계약 테스트: 266/266 PASS (100%) 달성.

8. 셀프 호스팅 루프 런타임 프리즈 스냅샷 (B-13 / Stage 2)

루프 기동 시 .agents/skills/ 를 $TMPDIR 에 1회 동결하고 스냅샷에서 재실행하여, 턴 도중 프레임워크 스킬 편집이 진행 중인 루프를 깨뜨리지 못하도록 차단.
코드 루트(스냅샷)와 상태 루트(MAM_REAL_ROOT)를 분리해 레지스트리·루프 락·diff 수집은 실제 저장소를 계속 사용.
재실행 시 원본 argv 를 배열로 보존해 인자 유실을 방지(파서가 $@ 를 소비하므로 필수).
스냅샷 생성 실패 시 log_* 정의 이전 구간임을 고려해 echo 로 경고하고 미동결 진행.
MAM_LOOP_NO_FREEZE=1 로 비활성화 가능. 스냅샷 생성 실패는 경고 후 기존 동작으로 폴백.
회귀 가드 5종 신설 — argv 보존, 파손 래퍼 면역, 스킬 트리 무오염(B-6 경계), 락 해제 및 스냅샷 정리(B-12 경계), 비활성화 스위치.
회귀 및 계약 테스트: 271/271 PASS (100%) 달성.

9. 감사 로그 루트 지연 평가 (B-9 / P4-1)

mqtt_common.LOGS_DIR 의 import 시점 cwd 고정을 제거하고 호출 시점에 해석하는 get_logs_dir() 를 도입. chdir 이후에도 감사 로그가 현재 워크스페이스에 정확히 기록됨.
PEP 562 모듈 __getattr__ 로 LOGS_DIR 속성 접근 하위 호환 유지(동적 평가).
PEP 562 __dir__ 병행 정의로 dir()·탭 완성 가시성 유지.
DELEGATE_JOB_LOGS_DIR 환경변수가 실행 중 변경까지 반영.
회귀 가드 5종 신설 — cwd 추종, 실제 파일 생성, 환경변수 동적 반영, 전역 재도입 차단, dir() 탐색성.
회귀 및 계약 테스트: 276/276 PASS (100%) 달성.

🛠️ `v1.4.0` — Stability, Cleanup & Safe Job Delegation (2026-08-16)

주요 마일스톤: 격리 잔재 정리, 서브셸 루프 락 조기 해제 버그 픽스, 신규 파일 캡처 및 경량화.

P2-2 (C-3a / C-4 레거시 격리 스텁 및 미사용 심볼 제거):
- lib.sh 내 빈 스텁 4종(provision_isolation, isolation_lever, isolation_env_prefix, isolation_cmd_args) 및 _REAL_HERDR_PATH 완전 삭제.
- registry.py::TERMINAL_STATUSES 및 create_session.sh::ISOLATE 제거.
P2-1 (B-6 / B-12 delegate_job_safe 안정화):
- .agents/skills/... 내 불필요한 .tmp 복사본 생성 제거 및 인플레이스 직접 실행(bash "$orig_script") 전환.
- 서브셸 내 trap으로 인한 루프 락 마커(.mam/loop-guard-active) 조기 삭제 결함(D1) 원천 차단.
P0-2 (O-2 중복 루프 기동 방지 원자적 락):
- loop_lock.sh 신설: set -C 기반 원자적 락 획득 및 PID + lstart 소유권 검증으로 동시 실행 방지.
P0-1 (B-7 외곽 diff 수집 및 미추적 파일 캡처):
- diff_collect.sh 도입: CWD 독립 $REPO_ROOT 기준 diff 수집 및 git ls-files -o 미추적 파일 병합.
B-4 (시프트 ls 동적 포시스 타임스탬프 복원):
- lib.sh 554행의 created=999999 하드코딩을 실시간 타임스탬프(int(time.time()))로 복원.
테스트 슈트 경량화:
- 노후화된 중복 레거시 테스트 7개 파일(1,559줄) 삭제 (cf51b2c).

🛡️ `v1.3.0` — Orchestrator Onboarding & Scoped Guarding (2026-08-15)

주요 마일스톤: 오케스트레이터 신원 격리 및 다중 에이전트 협업 가드레일 확립.

multi-agent-mux-orc-onboard 스킬 신설:
- 오케스트레이터(agy)의 대화 UUID를 .mam/agent-sessions.yaml 내 orchestrator_uuids 리스트로 등록.
- find_workspace_uuid 및 verify_session_uuid에서 오케스트레이터 UUID를 스킵하여 서브에이전트 세션 오염 방지.
O-3 (조건부 오케스트레이션 위임 가드 — Scoped Guard):
- 오케스트레이터가 /multi-agent-mux-loop 활성화 상태에서 직접 코드를 수정하지 않고 스크립트로 위임하도록 통제.
- AGENTS.md §5 및 MULTI_AGENT_RULES.md 내 가드레일 명시.
배포 및 패키징 파이프라인 현대화:
- deploy/lib_ownership.sh 신설 및 hooks.json 3-way 병합(MERGE_REGISTRY) 지원.
- Gitea CI/CD 파이프라인 (deploy/gitea-ci.yml) 연동.

🔌 `v1.2.0` — Universal Herdr Server Isolation & Cline Integration (2026-08-14)

주요 마일스톤: Herdr 단일 서버 격리 및 다중 AI 에이전트 확장.

Universal Herdr Session Isolation:
- HERDR_SESSION_NAME 기반으로 격리 서버를 통일하여 프로세스 충돌 방지.
Cline 에이전트 통합:
- cline CLI 기반 대화 세션 생성, 정지, 복원 및 TUI 레디 토큰 핸들링 지원.
SQLite WAL 트랜잭션 동시성:
- 세션 레지스트리 동시 쓰기 시 발생하는 락 충돌을 방지하기 위해 SQLite WAL 모드 전면 적용.

🧱 `v1.0.0` ~ `v1.1.0` — Initial Multi-Agent Mux Framework (2026-08-10 ~ 2026-08-13)

주요 마일스톤: 터미널 다중 에이전트 오케스트레이션 기초 설계 및 비동기 루프 완성.

핵심 수명주기 스킬군 구축: create, stop, resume, status, monitor 스킬 기본 구현.
MQTT 기반 비동기 잡 위임: multi-agent-mux-delegate-job을 통한 에이전트 간 이벤트 통신 및 결과 구독.
자율 협업 루프: multi-agent-mux-loop 컨트롤러를 통한 Planner-Creator-Reviewer 역할 분담 체계 정립.

🧪 품질 보증 및 검증 기준 (Verification Standards)

모든 릴리스는 다음 4단계 엄격한 검증을 통과해야 배포됩니다:

정적 문법 검사: bash -n (모든 셸 스크립트) 및 AST 미사용 코드 분석.
단위 및 컴포넌트 테스트 (Tier 1~2): 인플레이스 및 컴포넌트 간 상호작용 검증.
통합 및 계약 테스트 (Tier 3~4 / Contract): clean environment (env -u PYTHONPATH) 하에서의 어댑터 계약 및 CLI 브리지 검증.
멀티에이전트 교차 피어 리뷰: Planner(claude) 및 Reviewer(cline) 간 교차 검증 및 [VERDICT: PASS] 100% 합의.

19 KiB Raw Permalink Blame History

📜 Multi-Agent Mux 버전 이력 (VERSIONS.md)

📌 현재 버전 개요 (Current Release)

🧭 스킬 패키지 버전 매트릭스 (Skills Version Matrix)

📋 버전별 상세 변경 내역 (Changelog)

🚀 v2.2.1 — Single-Workspace 2xK Multi-Pane Tiling Optimization & Premature Overflow Fix (2026-08-24)

1. 2xK 레이아웃 엔진 최소 폭 완화 (lib_py/layout.py, lib.sh)

2. 경계값 및 타일링 자동화 테스트 확충 (tests/test_layout.py, tests/test_tier1_unit.py)

🚀 v2.2.0 — Herdr Workspace Label Standardization, Runtime Sync & Legacy Fallback Decoupling (2026-08-24)

1. --herdr-workspace 옵션 도입 및 Herdr 런타임 레이블 동기화