nomadcode/agent-roadmap/phase/external-integration/milestones/external-integration.md

Milestone: External Integration

위치

• Roadmap: agent-roadmap/ROADMAP.md
• Phase: agent-roadmap/phase/external-integration/PHASE.md

목표

Work Item Provider Pipeline Design과 workflow core 이후 남은 Plane/Jira 확장, Mattermost, IOP 실행 연결을 stub 또는 호환 호출 경로에서 실제 통합 흐름으로 확장한다. IOP 호출은 현재 단계에서 OpenAI-compatible Responses API 경로를 기본으로 하며, NomadCode/IOP 고유 실행 문맥은 metadata 확장으로 전달한다. NomadCode가 직접 모델 런타임을 호출하거나 IOP native protocol을 외부 호출 표면으로 사용하지 않는다.

상태

[진행중]

구현 잠금

• 상태: 잠금
• 결정 필요:
  • Mattermost와 Plane/Jira 결과 발행의 책임 경계를 결정한다.
  • Agent Integrator를 유지할지 IOP/A2A 또는 다른 연결 지점으로 대체할지 결정한다.
  • A2A 도입 시점을 이 Milestone 범위로 둘지 후속으로 미룰지 결정한다.

범위

• Plane work item 생성 / comment / status update 확장
• Jira issue 조회 / comment / status transition adapter 구현
• Mattermost 메시지 발송 구현
• 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을 기본 실행 경로로 전제하지 않도록 전환 기준 정리

기능

Epic: [external-integration] Provider and execution adapters

외부 work item provider, 협업 도구, 실행 표면을 adapter 경계 안에서 실제 통합 흐름으로 확장한다.

• [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를 별도 runtime이 아닌 IOP Node agent interface용 thin execution connector/adapter 경계로 재정의한다. 검증: Agent Integrator 또는 그 대체 연결 지점이 명확히 정의되어 있다.
• [iop-responses] IOP OpenAI-compatible Responses API 경로와 metadata 확장을 NomadCode의 기본 실행 호출 경로로 정리. 검증: IOP OpenAI-compatible Responses 호출 경로가 core workflow와 연결된다.
• [model-reclass] direct model endpoint / Ollama fallback 표현과 설정을 IOP 경유 호출 기준으로 재분류. 검증: NomadCode의 기본 실행 경로가 직접 모델 호출이 아니라 IOP 경유 호출임이 로드맵과 운영 문서에서 일관되게 읽힌다.
• [adapter-boundary] 외부 provider별 구현 경계 점검. 검증: provider 세부 구현이 adapter 경계 밖으로 새지 않는다.

완료 리뷰

• 상태: 없음
• 요청일: 없음
• 완료 근거: 없음
• 리뷰 필요:
  • 사용자가 완료 결과를 확인했다
  • archive 이동을 승인했다
• 리뷰 코멘트: 없음

범위 제외

• Outline / Forgejo / Nextcloud 연동
• MCP 서버
• Web Agent UI
• Flutter 앱 기능 구현
• IOP A2A JSON-RPC 기반 외부 agent 추가, task 상태, artifact, cancel 흐름 공유
• NomadCode가 IOP native protocol을 직접 외부 호출 경로로 사용하는 것
• IOP 내부 모델 라우팅, 모델 프로파일, RAG, MCP, output validation, fallback 정책 구현

작업 컨텍스트

• 이전 출처: services/core/README.md의 ## 단계별 다음 작업
• 주요 작업 영역: services/core/internal/adapters/, services/core/internal/scheduler/, services/core/internal/workflow/
• 선행 작업: Work Item Provider Pipeline Design, Workflow Core, Mattermost Nexo Messaging Alignment
• 후속 작업: Project Workspace Management UX
• 현재 지점: Workflow Core가 완료되어 Plane/Jira/Mattermost/Agent Integrator/IOP 호출 경계를 실제 adapter 흐름으로 확장하는 단계로 전환했다. 구현 전에는 구현 잠금의 결정 필요 항목을 먼저 확인한다.
• 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에 연결한다.
  • services/core/internal/scheduler/jobs.go는 model client 결과를 task completion 결과로 저장한다.
  • README.md와 services/core/README.md는 NomadCode의 기본 실행 호출을 IOP Edge OpenAI-compatible Responses 경로로 정리하고, direct Ollama/model endpoint는 local development compatibility로 재분류한다.
  • sibling IOP repository의 로드맵은 OpenAI-compatible API를 외부 모델 기반 호출 표면으로, A2A를 외부 agent 작업 위임 표면으로, IOP native protocol을 운영 제어 표면으로 분리한다.
• 확인 필요: 구현 잠금의 결정 필요 항목 참고.