From ff60ec369931b379ba10998696e4d107bc5dd337 Mon Sep 17 00:00:00 2001 From: toki Date: Wed, 3 Jun 2026 12:08:54 +0900 Subject: [PATCH] update: roadmap and README files --- README.md | 6 +++--- agent-roadmap/ROADMAP.md | 4 +++- .../milestones/external-integration.md | 19 +++++++++++-------- services/core/README.md | 5 ++--- 4 files changed, 19 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index cc30a43..54fc1db 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ NomadCode는 제품과 워크플로우 계층을 소유합니다. - 모바일/데스크톱/선택적 web target의 Flutter project management surface - top titlebar, 우측 activity rail, 중앙 content 전환, 우측 Agent dock, 하단 IOP section slot으로 구성되는 workbench shell - IOP 관리 page/tab에 외부 IOP console package 또는 widget을 선택적으로 mount하는 제품 조립 경계 -- IOP 호출에 넘길 task metadata 구성 +- IOP OpenAI-compatible 호출에 넘길 task/workspace/session metadata 구성 IOP는 실행과 최적화 계층을 소유합니다. @@ -31,7 +31,7 @@ IOP는 실행과 최적화 계층을 소유합니다. - OpenCode, Aider, Claude Code, Gemini CLI, Codex CLI 같은 CLI agent/runtime adapter - RAG, context compression, MCP/tool policy, output validation, retry/fallback, token/speed/quality optimization -NomadCode는 IOP가 제공하는 외부 표면을 통해 IOP를 호출합니다. 현재 기본 경로는 IOP의 OpenAI-compatible Responses API입니다. A2A는 향후 외부 agent delegation 작업을 위한 표면이며, IOP native protocol은 NomadCode의 기본 외부 호출 경로가 아닙니다. +NomadCode는 IOP가 제공하는 외부 표면을 통해 IOP를 호출합니다. 현재 기본 경로는 IOP의 OpenAI-compatible Responses API입니다. NomadCode는 OpenAI-compatible request/response shape를 기본 계약으로 채택하고, NomadCode/IOP 고유의 task, workspace, session, approval, artifact, notification 문맥은 별도 `iop` wrapper field가 아니라 `metadata` 확장으로 전달합니다. A2A는 향후 외부 agent delegation 작업을 위한 표면이며, IOP native protocol은 NomadCode의 기본 외부 호출 경로가 아닙니다. ## 빠른 시작 @@ -125,7 +125,7 @@ IOP 경계가 걸린 작업은 같은 workspace에 sibling IOP repository가 있 | Core | `DATABASE_URL` | 스크립트 사용 시 선택 | Core script는 local 기본값을 제공합니다. 다른 PostgreSQL을 쓰거나 binary를 직접 실행할 때 설정합니다. | | Core | `REDIS_URL`, `REDIS_KEY_PREFIX` | 스크립트 사용 시 선택 | worker/queue 상태에 사용할 Redis 주소와 key prefix입니다. | | Core | `AUTH_USERNAME`, `AUTH_PASSWORD` | 선택 | `AUTH_PASSWORD`를 설정하면 `/readyz`와 `/api/*`에 HTTP Basic Auth가 적용됩니다. | -| Core | `MODEL_BASE_URL`, `MODEL_API_KEY`, `MODEL_NAME`, `MODEL_CONTEXT_SIZE`, `MODEL_TIMEOUT_SEC` | 선택 | worker execution에서 사용할 IOP Edge OpenAI-compatible Responses endpoint 설정입니다. | +| Core | `MODEL_BASE_URL`, `MODEL_API_KEY`, `MODEL_NAME`, `MODEL_CONTEXT_SIZE`, `MODEL_TIMEOUT_SEC` | 선택 | worker execution에서 사용할 IOP Edge OpenAI-compatible Responses endpoint 설정입니다. IOP/NomadCode 전용 실행 문맥은 요청 `metadata`로 전달하는 방향을 기준으로 합니다. | | Core | `A2A_EDGE_URL`, `A2A_AGENT_URL`, `A2A_TOKEN`, `A2A_TIMEOUT_SEC` | 선택 | 향후 A2A-compatible agent delegation 경로 설정입니다. 현재 기본 실행 경로는 아닙니다. | | Core | `WORKFLOW_TASK_TIMEOUT_SEC` | 선택 | workflow task timeout 기본값을 조정합니다. | | Core | `MATTERMOST_BASE_URL`, `MATTERMOST_TOKEN` | 선택 | Mattermost adapter 연동용 설정입니다. | diff --git a/agent-roadmap/ROADMAP.md b/agent-roadmap/ROADMAP.md index deaf005..76b126e 100644 --- a/agent-roadmap/ROADMAP.md +++ b/agent-roadmap/ROADMAP.md @@ -6,6 +6,8 @@ NomadCode는 Flutter 기반 앱, core 서비스, 공유 계약, agent-operation 현재 로드맵은 `ROADMAP.md -> phase//PHASE.md -> phase//milestones/.md` scaffold를 기준으로 관리한다. React/Vite 웹 콘솔 제거, 서버/Plane/provider 기반 작업, Flutter-first 클라이언트 정리, Mattermost push plugin extraction, client integration 표준화는 완료되었다. 이후 core workflow 안정화, 외부 통합, Flutter-first 프로젝트 제어 UX를 먼저 정리하고, MCP 기반 agent-ops 제어 표면은 로드맵의 마지막으로 미룬다. +IOP 외부 실행 호출은 OpenAI-compatible Responses API 방식을 기본 계약으로 채택하고, NomadCode/IOP 고유의 task, workspace, session, approval, artifact, notification 문맥은 별도 `iop` wrapper field가 아니라 `metadata` 확장으로 전달한다. A2A는 agent-to-agent delegation이 명확히 필요할 때 재검토하며, IOP native protocol은 NomadCode의 기본 외부 실행 호출 표면으로 쓰지 않는다. + ## Phase 흐름 위에서 아래로 진행된 순서와 예정 흐름을 나타낸다. @@ -32,7 +34,7 @@ NomadCode는 Flutter 기반 앱, core 서비스, 공유 계약, agent-operation - 요약: proto-socket 내부 통신 레일을 정리한 뒤 client-core 통신과 실제 e2e 흐름을 기준으로 task lifecycle, retry, timeout, notification event를 안정화한다. - [진행중] External Integration - 경로: `agent-roadmap/phase/external-integration/PHASE.md` - - 요약: Workflow Core 재개 전에 Mattermost/Nexo messaging 정합성을 먼저 닫고, 이후 Plane 확장, Mattermost, Agent Integrator, IOP OpenAI API Responses-compatible 호출을 실제 통합 흐름으로 확장한다. + - 요약: Workflow Core 재개 전에 Mattermost/Nexo messaging 정합성을 먼저 닫고, 이후 Plane 확장, Mattermost, IOP OpenAI-compatible Responses 호출과 metadata 기반 실행 문맥 전달을 실제 통합 흐름으로 확장한다. - [계획] Project Workspace Management UX - 경로: `agent-roadmap/phase/project-workspace-management-ux/PHASE.md` - 요약: client integration 표준화는 완료했고, 실제 프로젝트 단위 앱 UX 구현은 core workflow와 외부 통합 기준 이후로 미룬다. diff --git a/agent-roadmap/phase/external-integration/milestones/external-integration.md b/agent-roadmap/phase/external-integration/milestones/external-integration.md index 23a2b70..3e6f604 100644 --- a/agent-roadmap/phase/external-integration/milestones/external-integration.md +++ b/agent-roadmap/phase/external-integration/milestones/external-integration.md @@ -7,7 +7,7 @@ ## 목표 -Work Item Provider Pipeline Design과 workflow core 이후 남은 Plane/Jira 확장, Mattermost, Agent Integrator, IOP 연결을 stub 또는 호환 호출 경로에서 실제 통합 흐름으로 확장한다. IOP 호출은 현재 단계에서 OpenAI API Responses-compatible 경로를 기본으로 하며, NomadCode가 직접 모델 런타임을 호출하거나 IOP native protocol을 외부 호출 표면으로 사용하지 않는다. +Work Item Provider Pipeline Design과 workflow core 이후 남은 Plane/Jira 확장, Mattermost, IOP 실행 연결을 stub 또는 호환 호출 경로에서 실제 통합 흐름으로 확장한다. IOP 호출은 현재 단계에서 OpenAI-compatible Responses API 경로를 기본으로 하며, NomadCode/IOP 고유 실행 문맥은 `metadata` 확장으로 전달한다. NomadCode가 직접 모델 런타임을 호출하거나 IOP native protocol을 외부 호출 표면으로 사용하지 않는다. ## 상태 @@ -17,8 +17,8 @@ Work Item Provider Pipeline Design과 workflow core 이후 남은 Plane/Jira 확 - 상태: 잠금 - 결정 필요: - - [ ] Mattermost와 Plane/Jira 결과 발행의 책임 경계를 결정한다. - - [ ] Agent Integrator를 유지할지 IOP/A2A 또는 다른 연결 지점으로 대체할지 결정한다. + - [x] Mattermost와 Plane/Jira 결과 발행의 책임 경계를 결정한다. + - [x] Agent Integrator를 유지할지 IOP/A2A 또는 다른 연결 지점으로 대체할지 결정한다. - [ ] A2A 도입 시점을 이 Milestone 범위로 둘지 후속으로 미룰지 결정한다. ## 범위 @@ -26,9 +26,9 @@ Work Item Provider Pipeline Design과 workflow core 이후 남은 Plane/Jira 확 - Plane work item 생성 / comment / status update 확장 - Jira issue 조회 / comment / status transition adapter 구현 - Mattermost 메시지 발송 구현 -- Agent Integrator 호출 구조 추가 -- IOP OpenAI API Responses-compatible 호출 구조 추가 -- IOP 외부 호출 표면은 OpenAI API 호환과 A2A만 전제하되, 현재 단계의 기본 호출은 OpenAI API Responses-compatible 경로로 한정 +- IOP Node agent interface를 호출하는 thin execution connector/adapter 경계 추가 +- IOP OpenAI-compatible Responses API 호출 구조와 metadata 기반 실행 문맥 전달 추가 +- IOP 외부 호출 표면은 OpenAI-compatible API를 기본으로 하고 A2A는 후속 결정 대상으로 두며, 현재 단계의 기본 호출은 OpenAI-compatible Responses API 경로로 한정 - NomadCode core가 직접 모델 endpoint 또는 Ollama fallback을 기본 실행 경로로 전제하지 않도록 전환 기준 정리 ## 기능 @@ -40,8 +40,8 @@ Work Item Provider Pipeline Design과 workflow core 이후 남은 Plane/Jira 확 - [ ] [plane-adapter-expand] Plane work item 생성, comment, status update adapter 확장. 검증: core가 Plane에 work item, comment, status update를 요청할 수 있다. - [ ] [jira-adapter] Jira issue 조회, comment, status transition adapter 구현. 검증: core가 Jira에 issue 조회, comment, status transition을 요청할 수 있다. - [ ] [mattermost-adapter] Mattermost 메시지 발송 adapter 구현과 `../nexo/packages/messaging_flutter` host notification boundary 정합성 유지. 검증: core가 Mattermost에 메시지를 발송하고, server-generated signed push smoke가 `agent-test/local/mattermost-server-generated-push-smoke.md` 기준으로 FCM/ACK/opened/reply/dismiss evidence를 남긴다. -- [ ] [agent-integrator] Agent Integrator 호출 경계 정의. 검증: Agent Integrator 또는 그 대체 연결 지점이 명확히 정의되어 있다. -- [x] [iop-responses] IOP OpenAI API Responses-compatible 경로를 NomadCode의 기본 실행 호출 경로로 정리. 검증: IOP OpenAI API Responses-compatible 호출 경로가 core workflow와 연결된다. +- [ ] [agent-integrator] Agent Integrator를 별도 runtime이 아닌 IOP Node agent interface용 thin execution connector/adapter 경계로 재정의한다. 검증: Agent Integrator 또는 그 대체 연결 지점이 명확히 정의되어 있다. +- [x] [iop-responses] IOP OpenAI-compatible Responses API 경로와 metadata 확장을 NomadCode의 기본 실행 호출 경로로 정리. 검증: IOP OpenAI-compatible Responses 호출 경로가 core workflow와 연결된다. - [x] [model-reclass] direct model endpoint / Ollama fallback 표현과 설정을 IOP 경유 호출 기준으로 재분류. 검증: NomadCode의 기본 실행 경로가 직접 모델 호출이 아니라 IOP 경유 호출임이 로드맵과 운영 문서에서 일관되게 읽힌다. - [ ] [adapter-boundary] 외부 provider별 구현 경계 점검. 검증: provider 세부 구현이 adapter 경계 밖으로 새지 않는다. @@ -75,9 +75,12 @@ Work Item Provider Pipeline Design과 workflow core 이후 남은 Plane/Jira 확 - Mattermost signed push smoke 재현 가이드: `agent-test/local/mattermost-server-generated-push-smoke.md` - private 환경값 router: `agent-test/local/mattermost-server-generated-push-smoke.md` (ignored local file) - Mattermost 책임 경계: core는 Mattermost REST 메시지 발송과 task notification 발행을 담당하고, `../nexo/packages/messaging_flutter`는 client-side FCM 수신, signature 검증, ACK, notification display, opened-routing, inline reply, dismiss를 담당한다. +- 결과 발행/알림 기준: 자동 알림은 Milestone 내부 모든 작업이 완료 체크되는 시점과 사용자 리뷰 요청 시점에 한정한다. 사용자가 현재 에이전트 대화 화면을 활성으로 보고 있으면 알림을 보내지 않고, 백그라운드 상태이거나 다른 workspace agent로 이동한 상태에서 메시지/작업이 완료되면 알림을 보낸다. 추가 알림 유형은 필요가 생길 때 별도 결정으로 확장한다. - Nexo host 정합성: NomadCode host는 Firebase 설정, Mattermost credential handoff, signing key, optional server identifier, navigation callback만 `MattermostPushClient` 경계로 전달한다. native push 처리 로직은 `apps/client/android`에 복제하지 않는다. - 선행 순서: Mattermost 메시지/알림 경계 정합성은 `agent-roadmap/archive/phase/external-integration/milestones/mattermost-nexo-messaging-alignment.md`에서 먼저 닫았고, 이후 `[mattermost-adapter]`는 core의 Mattermost REST 메시지 발송 구현에 집중한다. - Plane 제어 범위: 이 Milestone은 Plane work item 생성, comment, status update adapter 확장까지만 다룬다. Plane 상위 티켓/Milestone, 하위 티켓/Task 제어 흐름과 MCP 기반 agent-ops control plane은 `Agent-Ops MCP Control Plane` Phase로 미룬다. +- Agent runtime 연결 기준: Agent Shell은 실제 agent runtime이 아니라 사용자 대화 UX surface이며, 실제 agent는 IOP Node의 agent interface 뒤에 있다. 따라서 `Agent Integrator`는 별도 runtime이나 A2A 전제 계층으로 키우지 않고, NomadCode core에서 IOP Node agent interface를 호출하는 thin execution connector/adapter 경계로 재정의한다. +- IOP 호출 계약: 이번 Milestone의 기본 실행 호출 표면은 OpenAI-compatible Responses API로 정식 채택한다. NomadCode/IOP 전용 task/workspace/session/agent/approval/artifact/notification 의미는 별도 `iop` wrapper 필드를 만들지 않고 OpenAI-compatible `metadata` 또는 IOP native endpoint의 명시 필드로 전달한다. 완전 신규 프로토콜은 OpenAI-compatible 표면으로 task lifecycle, artifact, cancel, approval, streaming 요구를 감당하기 어렵다는 근거가 생길 때 재검토한다. - 현재 반영 근거: - `services/core/internal/adapters/openai/client.go`는 non-streaming `POST /v1/responses` 호출 경로를 사용한다. - `services/core/cmd/server/main.go`는 `MODEL_BASE_URL`, `MODEL_API_KEY`, `MODEL_NAME`, `MODEL_CONTEXT_SIZE`, `MODEL_TIMEOUT_SEC` 설정으로 OpenAI-compatible model client를 구성해 scheduler에 연결한다. diff --git a/services/core/README.md b/services/core/README.md index e052959..78bbea6 100644 --- a/services/core/README.md +++ b/services/core/README.md @@ -36,7 +36,7 @@ NomadCode Core는 사용자 요청을 작업 단위로 받고, 작업 상태를 로컬 실행은 현재 개발 호스트의 Go와 `code-server` compose에 붙은 PostgreSQL/Redis가 있다는 전제로 진행합니다. local 기본 `DATABASE_URL`은 `postgres://nomadcode:nomadcode@code-server-postgres:5432/nomadcode-core-local?sslmode=disable` 이고, local 기본 `REDIS_URL`은 `redis://code-server-redis:6379/3`, `REDIS_KEY_PREFIX`는 `nomadcode-core:local` 입니다. dev 배포는 Docker Compose로 실행하며, 같은 `code-server-postgres` Postgres와 `code-server-redis` Redis를 사용합니다. dev DB명은 `nomad-core-dev` 이고, dev 기본 `REDIS_URL`은 `redis://code-server-redis:6379/4`, `REDIS_KEY_PREFIX`는 `nomadcode-core:dev` 입니다. `AUTH_PASSWORD`를 설정하면 `/readyz`와 `/api/*`에 HTTP Basic Auth가 적용됩니다. -모델 호출의 기본 방향은 IOP Edge의 OpenAI-compatible Responses input surface입니다. `MODEL_BASE_URL`은 IOP Edge listener를 가리키고, 해당 listener는 non-streaming `POST /v1/responses`를 제공해야 합니다. 현재 코드와 local script에는 개발 호환용 direct model endpoint/Ollama 기본값이 남아 있을 수 있지만, 로드맵과 운영 기준의 기본 실행 경로는 IOP 경유 호출입니다. A2A agent 호출 endpoint는 `A2A_EDGE_URL`로 설정하고, 기존 `A2A_AGENT_URL`도 fallback alias로 받습니다. bearer token은 `A2A_TOKEN`, timeout은 `A2A_TIMEOUT_SEC`로 설정합니다. A2A는 향후 외부 agent delegation 표면이며 현재 기본 실행 경로는 아닙니다. Plane 연동은 `PLANE_BASE_URL`, `PLANE_TOKEN`으로 설정하며, toki-labs dev Plane 기본 URL은 `https://plane.toki-labs.com` 입니다. +모델 호출의 기본 방향은 IOP Edge의 OpenAI-compatible Responses input surface입니다. `MODEL_BASE_URL`은 IOP Edge listener를 가리키고, 해당 listener는 non-streaming `POST /v1/responses`를 제공해야 합니다. NomadCode는 OpenAI-compatible request/response shape를 기본 계약으로 유지하고, task/workspace/session/approval/artifact/notification 같은 IOP/NomadCode 전용 실행 문맥은 별도 `iop` wrapper field가 아니라 요청 `metadata` 확장으로 전달하는 방향을 기준으로 합니다. 현재 코드와 local script에는 개발 호환용 direct model endpoint/Ollama 기본값이 남아 있을 수 있지만, 로드맵과 운영 기준의 기본 실행 경로는 IOP 경유 호출입니다. A2A agent 호출 endpoint는 `A2A_EDGE_URL`로 설정하고, 기존 `A2A_AGENT_URL`도 fallback alias로 받습니다. bearer token은 `A2A_TOKEN`, timeout은 `A2A_TIMEOUT_SEC`로 설정합니다. A2A는 향후 외부 agent delegation 표면이며 현재 기본 실행 경로는 아닙니다. Plane 연동은 `PLANE_BASE_URL`, `PLANE_TOKEN`으로 설정하며, toki-labs dev Plane 기본 URL은 `https://plane.toki-labs.com` 입니다. `code-server` PostgreSQL 컨테이너에 DB를 생성하는 예시: @@ -82,7 +82,7 @@ MODEL_TIMEOUT_SEC="300" \ ./bin/run ``` -모델 호출은 OpenAI-compatible Responses API의 non-streaming `POST /v1/responses` 형식을 사용합니다. IOP Edge OpenAI-compatible listener를 `MODEL_BASE_URL`로 쓰려면 해당 listener가 `/v1/responses`를 제공해야 합니다. direct Ollama 호환 경로에서는 `MODEL_CONTEXT_SIZE`를 Ollama 전용 option인 `options.num_ctx`로 전달하지만, 이 경로는 IOP Responses listener가 준비되기 전의 local development compatibility로만 취급합니다. +모델 호출은 OpenAI-compatible Responses API의 non-streaming `POST /v1/responses` 형식을 사용합니다. IOP Edge OpenAI-compatible listener를 `MODEL_BASE_URL`로 쓰려면 해당 listener가 `/v1/responses`를 제공해야 합니다. NomadCode의 task/workspace/session 문맥은 OpenAI-compatible 표면을 깨는 별도 top-level wrapper가 아니라 `metadata` 확장으로 전달합니다. direct Ollama 호환 경로에서는 `MODEL_CONTEXT_SIZE`를 Ollama 전용 option인 `options.num_ctx`로 전달하지만, 이 경로는 IOP Responses listener가 준비되기 전의 local development compatibility로만 취급합니다. A2A agent 호출 인터페이스는 JSON-RPC 2.0 `message/send`, `tasks/get`, `tasks/cancel`을 우선 지원합니다. `A2A_EDGE_URL`을 설정하면 worker는 A2A `message/send`를 blocking 호출하고, 완료된 task/message 응답만 local task completion으로 반영합니다. 기존 `A2A_AGENT_URL`도 fallback alias로 받습니다. 현재 NomadCode의 기본 실행 경로는 OpenAI-compatible Responses 호출이며, A2A는 후속 agent delegation 작업에서 기본화 여부를 다시 결정합니다. @@ -212,4 +212,3 @@ NomadCode Core의 비동기 작업 재시도 및 타임아웃 처리는 다음 - **재-Enqueue 가능 여부 (Re-Enqueue Behavior)**: - 최종적으로 실패 상태(`failed`)인 작업은 다시 `queued`로 Enqueue하여 다시 처음부터 실행할 수 있습니다. - 반면 완료(`completed`) 또는 취소(`canceled`)된 터미널 상태의 작업은 다시 시작(Restart/Re-enqueue)할 수 없습니다. -