galaxis-agent/HANDOFF.md

HANDOFF: galaxis-agent 자율 개발 에이전트

Goal

galaxis-po (퇴직연금 퀀트 포트폴리오 관리) 코드베이스를 자율적으로 개발하는 SWE 에이전트(galaxis-agent)를 구축한다. open-swe를 포크하여 Gitea + Discord 환경에 맞게 커스터마이즈한다.

Infrastructure

• Agent Repo: ssh://git@152.69.231.161:7798/quant/galaxis-agent.git (로컬: ~/workspace/quant/galaxis-agent/)
• Target Repo: ssh://git@152.69.231.161:7798/quant/galaxis-po.git
• Oracle VM: A1 (4코어 ARM64, 24GB) - Gitea + Docker 운영 서버
• LLM: Claude API (Anthropic)
• Discord: 기존 봇 활용

Key Documents

• 설계 스펙: docs/superpowers/specs/2026-03-20-galaxis-agent-design.md (galaxis-po 리포, 2회 리뷰 완료)
• Phase 1 플랜: docs/superpowers/plans/2026-03-20-galaxis-agent-phase1.md (galaxis-po 리포)
• Phase 2 플랜: docs/superpowers/plans/2026-03-20-galaxis-agent-phase2.md (galaxis-po 리포)
• open-swe 원본: /Users/moneypenny/workspace/etc/open-swe/
• 메모리: /Users/moneypenny/.claude/projects/-Users-moneypenny-workspace-quant-galaxis-po/memory/MEMORY.md

Current Progress

Phase 1: 프로젝트 기반 구축 — COMPLETE

galaxis-agent 리포에 16개 커밋, 40개 테스트 전부 통과, Gitea에 push 완료.

완료된 작업:

1. open-swe 코드 복사 → galaxis-agent 리포 생성
2. 불필요 코드 삭제 (Linear, Slack, GitHub API, 클라우드 샌드박스 - 21개 파일)
3. github.py → git_utils.py 분리 (순수 git CLI 유틸리티 보존)
4. 의존성 정리 (PyJWT/langsmith/langchain-openai 등 제거, docker/discord.py/pydantic-settings 추가)
5. config.py 환경변수 모듈 (pydantic-settings, TDD)
6. Phase 2 스텁 파일 (DockerSandbox, GiteaClient, DiscordClient, gitea_comment, discord_reply)
7. 핵심 파일 정리 (server.py, webapp.py, prompt.py, commit_and_open_pr.py, open_pr.py)
8. Dockerfile (서버 + 샌드박스), docker-compose.yml (docker-socket-proxy 포함)
9. ARM64 호환성 검증: deepagents 0.4.11, langgraph, docker 7.1.0, discord 2.7.1 모두 OK

Phase 2: 핵심 기능 구현 — COMPLETE

실행 방식: Subagent-Driven Development (Task별 독립 subagent + spec 리뷰)

22개 커밋, 73개 테스트 통과 (40 Phase1 + 33 Phase2), Gitea에 push 완료.

Task	상태	커밋	설명
Task 1: DockerSandbox	✅ COMPLETE	5d44c2e	BaseSandbox 확장, docker-py 컨테이너 관리, 6 테스트
Task 2: GiteaClient	✅ COMPLETE	b2ad726	6 async API 메서드, lazy singleton, 8 테스트
Task 3: gitea_comment	✅ COMPLETE	e8983d8	asyncio.run()으로 GiteaClient 호출, 3 테스트
Task 4: commit_and_open_pr 완성	✅ COMPLETE	816415d	GiteaClient PR 생성, URL 변환, open_pr.py 안전망, 2 테스트
Task 5: discord_reply	✅ COMPLETE	e8983d8	DiscordClient + discord_reply 도구, 4 테스트
Task 6: 프롬프트 로딩	✅ COMPLETE	af7bd2c	read_repo_instructions() AGENTS.md+CLAUDE.md, 3 테스트
Task 7: 경로 검증	✅ COMPLETE	af7bd2c	path_validator.py, writable/blocked 경로 검증, 7 테스트
Task 8: LangGraph 검증	✅ COMPLETE	94edb45	langchain/langgraph-api:3.11 ARM64 동작 확인, docker-compose 추가
Task 9: 최종 테스트	✅ COMPLETE	-	73 테스트 통과, 7 모듈 import 확인, Gitea push 완료

Phase 3: 외부 연동 — COMPLETE

실행 방식: Subagent-Driven Development (Task별 독립 subagent + spec 리뷰)

8개 커밋, 107개 테스트 통과 (73 Phase1+2 + 34 Phase3), Gitea에 push 완료.

Task	상태	커밋	설명
Task 1: PersistentTaskQueue	✅ COMPLETE	0136823	SQLite 기반 영속 작업 큐, FIFO, 동시성 제한, 8 테스트
Task 2: MessageStore	✅ COMPLETE	9242bad	SQLite 기반 follow-up 메시지 스토어, check_message_queue 미들웨어 교체, 4 테스트
Task 3: Gitea Webhook 완성	✅ COMPLETE	8c274b4	이벤트 파싱, @agent 멘션 감지, rate limiting (10/min), 작업 큐잉, 6 테스트
Task 4: Discord Bot Gateway	✅ COMPLETE	5a47190	discord.py Bot Gateway, 멘션 파싱, 작업 큐 연동, 4 테스트
Task 5: Dispatcher	✅ COMPLETE	da9caca	백그라운드 큐 소비자, 에이전트 실행, 시작/실패 알림, 3 테스트
Task 6: Lifespan 통합	✅ COMPLETE	7e95aeb	FastAPI lifespan에 Discord bot + Dispatcher 통합
Task 7: Health Check	✅ COMPLETE	d35efae	/health, /health/gitea, /health/discord, /health/queue, 8 테스트
Task 8: 전체 검증	✅ COMPLETE	a58bbca	통합 테스트 (webhook→queue→dispatcher), 107 테스트 통과, import 확인

Phase 4: 안정화 & 자율 모드 — COMPLETE

실행 방식: Subagent-Driven Development (5개 독립 Task 병렬 → 2개 순차)

7개 커밋, 139개 테스트 통과 (107 Phase1-3 + 32 Phase4), Gitea에 push 완료.

Task	상태	커밋	설명
Task 1: CostGuard	✅ COMPLETE	edeb336	API 비용 추적/제한, 일일/작업당 한도, 8 테스트
Task 2: TaskHistory	✅ COMPLETE	db6e9b4	완료 작업 이력 DB (SQLite), 4 테스트
Task 3: Dispatcher 연동	✅ COMPLETE	c0cb4b7	CostGuard+TaskHistory를 Dispatcher에 통합, 2 테스트
Task 4: JSON 로깅	✅ COMPLETE	3f0d021	구조화 JSON 로깅, LOG_FORMAT 설정, 5 테스트
Task 5: Recovery	✅ COMPLETE	e82dfe1	서버 시작 시 복구, ContainerCleaner (30분 주기), 4 테스트
Task 6: AutoMerge	✅ COMPLETE	0c4c22b	E2E 조건부 자동 머지, blocked_paths 보호, 7 테스트
Task 7: webapp 통합	✅ COMPLETE	b2c52ab	Lifespan에 전 컴포넌트 통합, /health/costs 엔드포인트, 2 테스트

What Worked

• Subagent-driven development: Task별 독립 subagent 디스패치가 효율적. 컨텍스트 오염 없이 빠른 반복.
• Task 묶기: 유사한 Task를 하나의 subagent에 묶어 디스패치 (gitea_comment+discord_reply, prompt_loading+path_validator). 오버헤드 대폭 감소.
• sonnet 모델: Phase 2의 모든 구현 Task를 sonnet으로 처리. 스펙이 명확하면 sonnet이면 충분.
• Phase 2 플랜 리뷰: sync/async 인터페이스 불일치, 변수명 불일치, 잘못된 패턴 등을 플랜 리뷰에서 조기 발견하여 수정.
• LangGraph Server: langchain/langgraph-api:3.11 이미지가 ARM64에서 동작. SQLite 기본 모드 사용 가능. DATABASE_URI 환경변수 필요.

What Didn't Work / Watch Out For

• Task 번호 충돌: 플랜 수정 시 Task 번호가 중복됨. 큰 변경은 전체 재작성이 나음.
• Dockerfile 이름: subagent가 Dockerfile.agent로 만들었는데 docker-compose는 Dockerfile을 참조. 수동 교체 필요.
• 기본 브랜치: Gitea 리포 기본 브랜치 main, 로컬도 현재 main 브랜치.
• LangGraph Server: latest 태그 없음 → 3.11 태그 사용. DATABASE_URI 없으면 시작 실패. SQLite로 설정 시 Go Core API 정상 시작.
• module-level settings 인스턴스: settings = Settings()를 모듈 레벨에 두면 env var 없을 때 import 실패. 지연 초기화나 클래스만 export하는 방식 필요.
• BaseSandbox import 경로: deepagents.backends.sandbox.BaseSandbox (플랜에 적힌 deepagents.sandbox가 아님)
• ExecuteResponse import: deepagents.backends.protocol.ExecuteResponse
• 싱글턴 AsyncClient + asyncio.run() 충돌 위험: asyncio.run()이 이벤트 루프를 생성/종료하므로, 싱글턴 httpx.AsyncClient가 닫힌 루프에 바인딩될 수 있음. 도구마다 fresh client 생성 또는 sync httpx.Client 사용 고려.

Key Code Patterns

SandboxBackendProtocol.execute()는 동기

# server.py가 호출하는 방식:
result = await loop.run_in_executor(None, sandbox_backend.execute, cmd)

동기 도구에서 async GiteaClient 호출

# commit_and_open_pr.py, gitea_comment.py, discord_reply.py에서:
import asyncio
result = asyncio.run(client.create_pull_request(...))  # executor thread에서 안전

agents_md.py 패턴

loop = asyncio.get_event_loop()
result = await loop.run_in_executor(None, sandbox_backend.execute, cmd)

Next Steps

Phase 5: 배포 & 모니터링

Phase 4 완료로 프로덕션 안정성 확보. Phase 5에서는:

• Oracle VM 배포 자동화 (Ansible/Docker Compose)
• 모니터링 대시보드 (Grafana + SQLite → metrics)
• 알림 고도화 (Gitea PR 코멘트에 비용/소요시간 포함)
• 멀티 리포 지원 (galaxis-po 외 다른 리포)
• 1주일 conservative 운영 후 autonomous 전환

실행 방법

cd ~/workspace/quant/galaxis-agent
git log --oneline
uv run pytest tests/ -v  # 139 테스트 통과 확인