[Bug Fix Report] MAM 에이전트 생성 이슈 분석 및 수정 보고서 (OpenCode TUI 토큰 & lib.sh 런타임 제어) #2

New Issue

2026-08-30T02:54:38Z

Godopu commented

2026-08-30 02:54:38 +00:00

Multi-Agent Mux (MAM) 에이전트 생성 이슈 분석 및 수정 보고서

1. 개요 (Overview)

MAM(Multi-Agent Mux) 오케스트레이션 환경에서 opencode 리뷰어 에이전트(reviewer-opencode-01) 생성 과정에서 발생했던 TUI 준비 감지 대기 문제와 lib.sh 런타임 제어 보완 사항에 대한 기술 분석 및 수정 내역입니다.

2. 세부 문제 원인 및 수정 내역

2.1. OpenCode TUI 감지 토큰 불일치 (핵심 원인)

대상 파일: .agents/skills/lib_py/agents/adapters/opencode.py
원인 분석:
- OpenCode CLI가 실행되면 터미널 상단 로고가 일반 텍스트가 아닌 **ASCII 특수문자 블록(█▀▀█...)**으로 렌더링됩니다.
- 기존 어댑터의 ready_tokens 설정값이 단순히 'OpenCode|Chat'으로만 지정되어 있어, 프로세스가 정상적으로 기동되었음에도 wait_for_tui_ready 함수가 화면 텍스트를 감지하지 못하고 30초 대기(타임아웃)에 빠졌습니다.

🔧 코드 변경 사항 (Diff)

# 수정 전 (opencode.py)
    @property
    def ready_tokens(self) -> str:
        return 'OpenCode|Chat'

# 수정 후 (opencode.py)
    @property
    def ready_tokens(self) -> str:
        return 'OpenCode|Chat|Ask anything|tab agents|ctrl\\+p|Build auto|commands'

개선 효과:
- 실제 OpenCode CLI의 화면 요소인 프롬프트 문구(Ask anything...), 모드 표시(Build auto), 단축키 힌트(tab agents, ctrl+p, commands)를 즉시 감지하여 1초 이내에 정상 준비 완료로 판정합니다.

2.2. Herdr 런타임 심(Shim) 및 세션 제어 보완 (`lib.sh`)

MAM 스킬 업데이트 후 발생할 수 있는 Herdr 통신 및 모듈 임포트 문제를 함께 보완했습니다.

① Shim 래퍼 내 `PYTHONPATH` 누락 보완

대상 파일: .agents/skills/lib.sh
원인: Herdr translation shim(.mam/shim/herdr) 내부에서 python3 -m lib_py.layout 또는 lib_py.agents를 호출할 때 PYTHONPATH가 지정되지 않아 ModuleNotFoundError: No module named 'lib_py'가 발생할 수 있던 문제.
수정 내용: Shim 템플릿 헤더에 export PYTHONPATH="$_SKILL_DIR:${PYTHONPATH:-}" 자동 주입 추가.

# lib.sh 헤더 주입 코드
_SHIM_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
_SKILL_DIR="$(cd "$_SHIM_DIR/../../.agents/skills" 2>/dev/null && pwd || true)"
[ -n "$_SKILL_DIR" ] && export PYTHONPATH="$_SKILL_DIR:${PYTHONPATH:-}"

② `herdr agent start` 타임아웃 및 실행 폴백 추가

대상 파일: .agents/skills/lib.sh
원인: TUI 렌더링에 1~2초 지연이 발생하여 Herdr CLI가 timed out waiting for agent startup을 반환할 경우, 이를 실패로 간주하고 생성 중이던 페인을 강제 파괴하던 문제.
수정 내용: 타임아웃 발생 시에도 프로세스가 살아있으면 성공으로 처리하고, 미기동 시 pane send-text로 에이전트 실행 명령을 전송하는 폴백 로직 추가.

③ 페인 ID 직접 전달 및 워크스페이스 라벨 매칭 지원

대상 파일: .agents/skills/lib.sh
원인: Herdr 내부 워크스페이스 ID(wF)와 사용자가 지정한 라벨(mam-agents) 간의 매칭이 어긋날 경우 페인 검색에 실패하는 문제.
수정 내용: 대상이 이미 페인 ID 형식(wN:pM)인 경우 즉시 반환하고, workspace_id 외에 label 및 workspace_label도 함께 매칭하도록 확장.

3. 최종 검증 결과

수정 사항 적용 후 reviewer-opencode-01 세션 생성이 1초 이내에 정상 완료되었으며, graceful stop 시 고유 세션 ID까지 안전하게 보존되었습니다.

세션명	에이전트	할당 역할	캡처된 고유 대화 ID (UUID)	복원 가능 상태
`planner-reviewer-claude-01`	`claude`	`planner, reviewer`	`43c3110e-7bdd-4d3c-b36e-cfba94cd1f04`	✅ `resumable`
`reviewer-creator-grok-01`	`grok`	`reviewer, creator`	`18f3e028-c8fe-40c6-ae4f-20d513582e93`	✅ `resumable`
`creator-agy-01`	`agy`	`creator`	`f9744f88-2e1f-489f-a621-1679a4018fdd`	✅ `resumable`
`reviewer-opencode-01`	`opencode`	`reviewer`	`ses_fb2098b87ffenhiEntaW2HMtp7`	✅ `resumable`

작성 일시: 2026-08-29 (UTC)

# Multi-Agent Mux (MAM) 에이전트 생성 이슈 분석 및 수정 보고서 ## 1. 개요 (Overview) MAM(Multi-Agent Mux) 오케스트레이션 환경에서 `opencode` 리뷰어 에이전트(`reviewer-opencode-01`) 생성 과정에서 발생했던 TUI 준비 감지 대기 문제와 `lib.sh` 런타임 제어 보완 사항에 대한 기술 분석 및 수정 내역입니다. --- ## 2. 세부 문제 원인 및 수정 내역 ### 2.1. OpenCode TUI 감지 토큰 불일치 (핵심 원인) - **대상 파일:** [`.agents/skills/lib_py/agents/adapters/opencode.py`](../../.agents/skills/lib_py/agents/adapters/opencode.py#L22-L26) - **원인 분석:** - OpenCode CLI가 실행되면 터미널 상단 로고가 일반 텍스트가 아닌 **ASCII 특수문자 블록(`█▀▀█...`)**으로 렌더링됩니다. - 기존 어댑터의 `ready_tokens` 설정값이 단순히 `'OpenCode|Chat'`으로만 지정되어 있어, 프로세스가 정상적으로 기동되었음에도 `wait_for_tui_ready` 함수가 화면 텍스트를 감지하지 못하고 30초 대기(타임아웃)에 빠졌습니다. #### 🔧 코드 변경 사항 (Diff) ```python # 수정 전 (opencode.py) @property def ready_tokens(self) -> str: return 'OpenCode|Chat' # 수정 후 (opencode.py) @property def ready_tokens(self) -> str: return 'OpenCode|Chat|Ask anything|tab agents|ctrl\\+p|Build auto|commands' ``` - **개선 효과:** - 실제 OpenCode CLI의 화면 요소인 프롬프트 문구(`Ask anything...`), 모드 표시(`Build auto`), 단축키 힌트(`tab agents`, `ctrl+p`, `commands`)를 즉시 감지하여 1초 이내에 정상 준비 완료로 판정합니다. --- ### 2.2. Herdr 런타임 심(Shim) 및 세션 제어 보완 (`lib.sh`) MAM 스킬 업데이트 후 발생할 수 있는 Herdr 통신 및 모듈 임포트 문제를 함께 보완했습니다. #### ① Shim 래퍼 내 `PYTHONPATH` 누락 보완 - **대상 파일:** [`.agents/skills/lib.sh`](../../.agents/skills/lib.sh#L154-L160) - **원인:** Herdr translation shim(`.mam/shim/herdr`) 내부에서 `python3 -m lib_py.layout` 또는 `lib_py.agents`를 호출할 때 `PYTHONPATH`가 지정되지 않아 `ModuleNotFoundError: No module named 'lib_py'`가 발생할 수 있던 문제. - **수정 내용:** Shim 템플릿 헤더에 `export PYTHONPATH="$_SKILL_DIR:${PYTHONPATH:-}"` 자동 주입 추가. ```bash # lib.sh 헤더 주입 코드 _SHIM_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" _SKILL_DIR="$(cd "$_SHIM_DIR/../../.agents/skills" 2>/dev/null && pwd || true)" [ -n "$_SKILL_DIR" ] && export PYTHONPATH="$_SKILL_DIR:${PYTHONPATH:-}" ``` #### ② `herdr agent start` 타임아웃 및 실행 폴백 추가 - **대상 파일:** [`.agents/skills/lib.sh`](../../.agents/skills/lib.sh#L807-L822) - **원인:** TUI 렌더링에 1~2초 지연이 발생하여 Herdr CLI가 `timed out waiting for agent startup`을 반환할 경우, 이를 실패로 간주하고 생성 중이던 페인을 강제 파괴하던 문제. - **수정 내용:** 타임아웃 발생 시에도 프로세스가 살아있으면 성공으로 처리하고, 미기동 시 `pane send-text`로 에이전트 실행 명령을 전송하는 폴백 로직 추가. #### ③ 페인 ID 직접 전달 및 워크스페이스 라벨 매칭 지원 - **대상 파일:** [`.agents/skills/lib.sh`](../../.agents/skills/lib.sh#L343-L375) - **원인:** Herdr 내부 워크스페이스 ID(`wF`)와 사용자가 지정한 라벨(`mam-agents`) 간의 매칭이 어긋날 경우 페인 검색에 실패하는 문제. - **수정 내용:** 대상이 이미 페인 ID 형식(`wN:pM`)인 경우 즉시 반환하고, `workspace_id` 외에 `label` 및 `workspace_label`도 함께 매칭하도록 확장. --- ## 3. 최종 검증 결과 수정 사항 적용 후 `reviewer-opencode-01` 세션 생성이 1초 이내에 정상 완료되었으며, graceful stop 시 고유 세션 ID까지 안전하게 보존되었습니다. | 세션명 | 에이전트 | 할당 역할 | 캡처된 고유 대화 ID (UUID) | 복원 가능 상태 | | :--- | :---: | :---: | :--- | :---: | | **`planner-reviewer-claude-01`** | `claude` | `planner, reviewer` | `43c3110e-7bdd-4d3c-b36e-cfba94cd1f04` | ✅ `resumable` | | **`reviewer-creator-grok-01`** | `grok` | `reviewer, creator` | `18f3e028-c8fe-40c6-ae4f-20d513582e93` | ✅ `resumable` | | **`creator-agy-01`** | `agy` | `creator` | `f9744f88-2e1f-489f-a621-1679a4018fdd` | ✅ `resumable` | | **`reviewer-opencode-01`** | `opencode` | `reviewer` | `ses_fb2098b87ffenhiEntaW2HMtp7` | ✅ `resumable` | --- *작성 일시: 2026-08-29 (UTC)*

Godopu closed this issue

2026-08-30 12:27:56 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: tmpl/multi-agent-mux#2

[Bug Fix Report] MAM 에이전트 생성 이슈 분석 및 수정 보고서 (OpenCode TUI 토큰 & lib.sh 런타임 제어) #2