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-compatible provider 추상화, Mattermost, IOP 실행 연결을 stub 또는 호환 호출 경로에서 실제 통합 흐름으로 확장한다. IOP 호출은 현재 단계에서 OpenAI-compatible Responses API 경로를 기본으로 하며, NomadCode/IOP 고유 실행 문맥은 metadata 확장으로 전달한다. NomadCode가 직접 모델 런타임을 호출하거나 IOP native protocol을 외부 호출 표면으로 사용하지 않는다.

상태

[진행중]

구현 잠금

상태: 해제
결정 필요:
- Mattermost와 Plane/Jira 결과 발행의 책임 경계를 결정한다.
- Agent Integrator를 유지할지 IOP/A2A 또는 다른 연결 지점으로 대체할지 결정한다.
- A2A는 이 Milestone 범위로 들이지 않고, 외부 agent-to-agent delegation 필요가 명확해질 때 후속 Milestone에서 재검토한다.

범위

provider별 HTTP handler를 늘리지 않아도 workitem.Reader/provider registry로 같은 intake pipeline을 탈 수 있는 provider-neutral 연결 구조
Plane work item 생성 / comment / status update 확장
Jira live API 구현은 테스트 환경이 생길 때까지 범위에서 제외하고, provider-neutral work item 계약이 Jira issue / comment / status transition 의미를 수용할 수 있게 추상화
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 경계 안에서 실제 통합 흐름으로 확장한다.

[provider-intake-registry] Plane 전용 task intake handler를 provider-neutral registry/generic route 또는 동등한 조립 구조로 정리해, 새 provider가 workitem.Reader와 필요한 capability facet만 구현하면 같은 work item -> core task pipeline을 재사용할 수 있게 한다. 검증: Plane 기존 경로는 호환되거나 같은 registry를 통해 동작하고, Jira-compatible provider를 붙일 때 provider별 task handler/route를 새로 만들 필요가 없다.
[plane-adapter-expand] Plane work item 생성, comment, status update adapter 확장. 검증: core가 Plane에 work item, comment, status update를 요청할 수 있다.
[jira-adapter] Jira live provider 구현은 테스트 환경이 생길 때까지 범위에서 제외하고, provider-neutral work item 계약이 Jira issue 조회, comment, status transition 의미를 수용할 수 있게 추상화한다. 검증: Jira credential 없이도 core의 provider-neutral contract/unit tests가 Jira-compatible state/comment/projection 요구를 설명하고, live Jira API 호출/e2e를 요구하지 않는다.
[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를 남긴다.
[adapter-boundary] 외부 provider별 구현 경계 점검. 검증: provider 세부 구현이 adapter 경계 밖으로 새지 않는다.
[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 경유 호출임이 로드맵과 운영 문서에서 일관되게 읽힌다.

완료 리뷰

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

범위 제외

Outline / Forgejo / Nextcloud 연동
Jira live API adapter 완성, 실제 Jira credential 기반 e2e smoke, Jira Cloud 운영 검증
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 Phase가 [완료]로 archive되었고, 현재 작업은 [provider-intake-registry]를 먼저 정리해 Plane/Jira-compatible/Mattermost 등 provider 확장이 같은 work item intake pipeline을 재사용하게 만드는 단계다. Jira는 현재 테스트 환경이 없으므로 live provider 구현 완료가 아니라 provider-neutral 추상화 적합성까지만 이 Milestone에서 다룬다. 구현 잠금의 직접 결정 항목은 현재 기준으로 해소되어 표준선에 따라 구현 계획을 만들 수 있다.
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로 미룬다.
Provider pipeline 현재 상태: services/core/internal/workitem과 services/core/internal/workitempipeline은 provider-neutral 계약을 갖고 있지만, HTTP intake wiring은 Plane 전용 route/handler에 치우쳐 있다. 이 Milestone에서는 [provider-intake-registry]로 상위 연결부를 정리해 provider 추가가 adapter/capability facet 확장 중심으로 닫히게 한다.
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 경계로 재정의한다.
A2A 결정: 이번 Milestone은 A2A JSON-RPC 기반 외부 agent 추가, task 상태, artifact, cancel 흐름 공유를 구현하지 않는다. A2A는 IOP OpenAI-compatible Responses 표면으로 감당하기 어려운 agent-to-agent delegation 요구가 명확해질 때 후속 Milestone에서 재검토한다.
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 요구를 감당하기 어렵다는 근거가 생길 때 재검토한다.
현재 반영 근거:
- [agent-integrator]는 별도 runtime이나 A2A 전제 계층이 아니라 NomadCode core에서 IOP Node agent interface를 호출하는 thin execution connector/adapter 경계로 정의했다.
- 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을 운영 제어 표면으로 분리한다.
확인 필요: 없음.

11 KiB Raw Blame History