Kiro CLI provider 지원 추가 및 세션 처리 보강

[ddiiwoong]

개요

이 PR은 cokacdir에 Kiro CLI provider 지원을 추가합니다.
기존에는 Claude / Codex / Gemini / OpenCode만 지원했지만, 이번 변경으로 kiro-cli를 별도 provider로 인식하고 텔레그램/스케줄/세션 관리 흐름에 연결할 수 있게 됩니다.

핵심 목표는 다음 3가지입니다.

1. kiro-cli chat를 cokacdir의 비대화형 스트리밍 실행 모델에 안전하게 연결할 것
2. Kiro의 디렉터리 기반 persistence 특성을 기존 UUID 중심 세션 모델과 충돌 없이 수용할 것
3. 사용자가 실제로 설정/재개/진단할 수 있도록 문서와 /session 동작까지 정리할 것

---

배경

Kiro는 다른 provider들과 세션 모델이 다릅니다.
Claude / Codex / Gemini / OpenCode는 외부 세션 ID 또는 이름 기반으로 세션을 찾고 재개하는 흐름이 비교적 분명한 반면,
Kiro CLI는 공식적으로 현재 디렉터리 기준의 대화 persistence(kiro-cli chat --resume)를 중심으로 동작합니다.

이 차이 때문에 단순히 "provider 하나 추가" 수준으로 붙이면 다음 문제가 생깁니다.

• Kiro.app GUI 런처를 잘못 잡으면 headless chat 실행이 되지 않음
• standalone kiro-cli 위치가 환경마다 달라서 탐색 로직이 필요함
• Kiro 세션은 UUID 조회보다 작업 디렉터리 재개가 더 중요함
• --no-interactive 환경에서 툴 승인 플래그가 없으면 Kiro가 실제 툴 실행을 못 하고 응답 품질이 급락함
• /session / 문서 / 로컬 세션 스냅샷 저장 규칙이 기존 provider와 다르게 처리되어야 함

이번 PR은 위 차이를 cokacdir 쪽에서 명시적으로 흡수합니다.

---

주요 변경 사항

1. 신규 Kiro adapter 추가

신규 파일 src/services/kiro.rs를 추가했습니다.

이 adapter는 다음 역할을 담당합니다.

• standalone kiro-cli 실행 파일 탐색
• 필요 시 JS entrypoint를 node로 실행
• kiro-cli chat 비대화형 호출 인자 구성
• stdout/stderr 스트리밍 처리
• ANSI 제거 및 개행 정규화
• Kiro 특유의 오류/빈 응답 감지
• 기존 CancelToken, process group, debug log 체계 재사용

구체적으로는 다음 탐색 순서를 사용합니다.

• COKAC_KIRO_PATH
• ~/.local/bin/kiro-cli
• ~/bin/kiro-cli
• /opt/homebrew/bin/kiro-cli
• /usr/local/bin/kiro-cli
• /usr/bin/kiro-cli
• which kiro-cli
• bash -lc "which kiro-cli"

또한 .js, .mjs, .cjs entrypoint를 직접 가리키는 경우 node <entrypoint> 형태로 실행하도록 처리했습니다.

반대로 Kiro.app는 자동 탐지 대상에서 제외했습니다.
이 런처는 GUI를 띄우는 성격이라 cokacdir가 기대하는 headless/plain-text chat 실행과 맞지 않기 때문입니다.

---

2. Kiro 비대화형 실행 인자 및 tool trust 처리

Kiro adapter는 다음 형태로 명령을 구성합니다.

• 새 세션: kiro-cli chat --trust-all-tools --no-interactive --wrap never <prompt>
• 명시적 세션 재개: --resume-id <id>
• 동일 디렉터리 재개: --resume

특히 이번 PR에서 중요한 부분은 tool trust 플래그입니다.

Kiro는 --no-interactive 상태에서 tool approval이 발생하면 실제 툴 실행이 멈추거나, 승인 필요 상태에서 fallback성 응답을 내보낼 수 있습니다.
이를 방지하기 위해 다음 정책을 넣었습니다.

• 기본 또는 non-empty tool set: --trust-all-tools
• 명시적으로 tool list가 비어 있는 경우: --trust-tools=

즉, 비대화형 Kiro 실행이 실제로 유용하게 동작하도록 cokacdir 쪽에서 승인 deadlock을 피하도록 했습니다.

---

3. 텔레그램 provider 파이프라인에 Kiro 연결

src/services/telegram.rs에서 Kiro를 provider로 연결했습니다.

포함된 내용은 다음과 같습니다.

• kiro model/provider 감지
• /model kiro 지원
• 일반 대화 요청 처리 경로에 Kiro adapter 연결
• bot message 처리 경로에 Kiro adapter 연결
• schedule 실행 경로에 Kiro adapter 연결
• provider 목록/표시 문자열에 Kiro 반영

결과적으로 Kiro는 단순 표시만 되는 provider가 아니라,
실제 대화/스케줄 실행 흐름에 Claude/Codex/Gemini/OpenCode와 동일한 수준으로 편입됩니다.

---

4. Kiro 세션 저장 방식을 UUID 기반이 아닌 "provider + path" 기반으로 보강

기존 세션 저장 로직은 대부분 session_id가 있을 것을 전제로 움직입니다.
하지만 Kiro는 directory-based persistence가 핵심이기 때문에, cokacdir 내부 스냅샷 파일도 그 특성에 맞춰 저장해야 합니다.

이번 PR에서는:

• session_storage_file_stem() 도입
• 일반 provider는 기존처럼 안전한 session_id 기반 파일명 사용
• Kiro는 provider + current_path를 해시한 kiro-<hash> 형태 파일명 사용
• session_id가 비어 있어도 Kiro session snapshot을 저장 가능

이렇게 해서 Kiro는 UUID가 노출되지 않아도:

• 동일 디렉터리에서 이전 대화 이력 복원 가능
• ~/.cokacdir/ai_sessions 내 로컬 snapshot 유지 가능
• /start <path> 재진입 시 자체 snapshot 기반 복원 가능

이라는 흐름을 갖게 됩니다.

---

5. /session 응답 및 session semantics를 Kiro에 맞게 분기

Kiro는 UUID 기반 재개보다 디렉터리 재개가 핵심이므로,
/session 응답도 일반 provider와 동일하게 보여주면 오해를 유발합니다.

이번 PR에서는 Kiro의 경우:

• 세션 ID가 없더라도 현재 작업 디렉터리와 재개 명령을 안내
• cd "<path>"; kiro-cli chat --resume 형태의 실제 재개 명령 제시
• 일반 provider와는 다른 “directory-based” 설명 출력

즉 사용자 입장에서 Kiro 세션을 어떻게 이어야 하는지가 훨씬 명확해집니다.

---

6. UUID 기반 /start <session_id> 흐름에서 Kiro를 명시적으로 분리

문서와 로직 모두에서 Kiro를 "UUID/name lookup provider"처럼 보이게 두지 않도록 정리했습니다.

핵심 의도는 다음과 같습니다.

• Claude / Codex / Gemini / OpenCode: 외부 session store 기반 조회 가능
• Kiro: 현재는 directory-based restore 중심

그래서 문서에서는 /start <kiro_session_id> 같은 사용법을 암시하지 않도록 수정했고,
실제 구현에서도 Kiro 내부 저장소를 UUID로 파싱하는 방식 대신 cokacdir의 local snapshot + current path 조합으로 다루도록 방향을 고정했습니다.

---

7. 환경변수 및 사용자 문서 보강

문서 변경도 함께 포함했습니다.

환경변수 문서

COKAC_KIRO_PATH를 추가하고 다음을 설명합니다.

• standalone binary override 방법
• JS entrypoint를 node로 실행하는 규칙
• Unix/Windows별 fallback resolver
• Kiro.app 자동 탐지 제외 이유

세션 문서

Kiro의 session semantics를 기존 provider들과 구분해서 설명합니다.

• Kiro는 UUID보다 directory-based restore가 핵심
• /session에서 보여주는 재개 명령의 의미
• /clear 이후에도 Kiro는 새 directory-based conversation을 시작한다는 점

README / 웹 문서

• provider 목록에 Kiro 추가
• env var 목록에 Kiro 추가
• 웹 문서의 세션/환경변수 섹션 반영

---

테스트 / 검증

다음 검증을 수행했습니다.

자동 테스트

• cargo test kiro -- --nocapture
• cargo check
• cargo build

모두 통과했습니다.

추가 테스트 포인트

src/services/kiro.rs에 다음 테스트를 추가/보강했습니다.

• 새 세션 인자 구성 테스트
• --resume-id 인자 구성 테스트
• --resume 인자 구성 테스트
• no_session_persistence일 때 resume 생략 테스트
• empty allowed tools -> --trust-tools= 테스트
• non-empty allowed tools -> --trust-all-tools 테스트
• ~/.local/bin/kiro-cli 탐색 테스트

src/services/telegram.rs에는 Kiro smoke test를 추가/보강해 다음을 검증합니다.

• /model kiro 설정 가능 여부
• Kiro에 prompt가 positional arg로 전달되는지
• stdin이 비어 있는지
• --trust-all-tools --no-interactive --wrap never 인자 순서가 맞는지
• Kiro session snapshot이 저장되는지
• /session이 directory-based 안내 문구와 kiro-cli chat --resume 명령을 보여주는지

---

사용자 영향

이 PR 이후 사용자는 다음이 가능해집니다.

• cokacdir에서 Kiro를 provider로 선택
• Kiro CLI를 별도 env var로 지정 가능 (COKAC_KIRO_PATH)
• 동일 작업 디렉터리에서 Kiro 대화 복원
• /session을 통해 Kiro 재개 명령을 바로 확인
• 텔레그램 일반 대화 및 schedule 실행에서 Kiro 사용

---

제한 사항 / 후속 과제

이번 PR은 Kiro CLI provider support에 초점을 둔 변경입니다.
다음은 아직 범위 밖입니다.

• Kiro의 native spec-driven workflow 전체 노출
• --agent-engine kas / --mode spec 제어 UI
• /spec ... 계열 인터랙티브 명령을 cokacdir 내부 기능으로 직접 매핑하는 작업
• Kiro 고유 artifact/workflow viewer 연동

즉 현재 단계에서의 목표는
Kiro를 cokacdir의 일반 provider 모델에 안정적으로 통합하는 것이며,
Kiro 고유의 spec-driven 경험을 100% 재현하는 것은 후속 작업으로 보는 것이 맞습니다.

---

리뷰 포인트

리뷰 시 특히 봐주시면 좋은 부분은 다음입니다.

1. Kiro의 directory-based persistence를 cokacdir 세션 모델 안에 녹여낸 방식이 타당한지
2. --no-interactive + tool trust 정책이 현재 운영 환경에서 안전하고 실용적인지
3. /session / 문서 설명이 Kiro의 실제 사용 패턴을 충분히 정확하게 반영하는지
4. provider 추가에 따른 기존 provider 회귀 위험이 없는지