
AI 에이전트 운영체제
JARVIS - Personal AI Operating System
여러 AI 모델과 도구를 미션 단위로 실행하는 개인용 AI 운영체제입니다. 협의, 실행, 승인, 메모리 구조와 Fastify 오케스트레이터, Next.js HUD를 구현했습니다.
01 / 담당 범위
요청을 받는 것과 실행을 끝내는 것은 다릅니다.
Fastify 오케스트레이터와 Next.js 운영 화면을 연결한 개인용 AI 운영체제입니다. 요청, 모델 선택, 승인, 실행 결과를 하나의 채팅 응답 속에 감추지 않고 각각의 역할로 다룹니다.
오케스트레이션 백엔드, 모듈형 HUD, 작업 공간과 승인 화면, 검증 도구를 개발했습니다. 아래 공개 코드 링크는 2026년 3월 28일 커밋을 기준으로 고정했습니다.
02 / 책임 구조
실행 요청에서 결과 확인까지.
실행 요청 · code / compute
- 요청 · Request
맥락과 사용할 모델을 정합니다
입력을 검증하고 사용자, 메모리 맥락, 공급자 자격 정보와 모델 선호를 확인합니다. 멱등성 키도 필수로 받습니다.
- 실행 식별 · Run
기존 실행을 찾거나 새로 만듭니다
사용자와 멱등성 키로 기존 실행을 조회합니다. 이미 있으면 해당 기록을 반환하고, 없으면 실행을 생성해 비동기 작업을 시작합니다.
- 결과 · Result
이벤트로 실행 상태를 확인합니다
새 작업의 접수와 완료를 구분합니다. SSE 엔드포인트는 저장된 실행을 확인해 진행·완료·실패 상태를 전달합니다.
실행 기록과 스트림 연결을 구분
확인한 SSE 핸들러는 저장된 실행 상태를 읽고 완료·실패·시간 초과 시 연결을 닫습니다. 실행 기록과 스트림은 서로 다른 객체이며, 자동 이벤트 재전송이나 exactly-once 실행을 보장한다고 설명하지 않습니다.
설계에서 나눈 것들.
요청 접수와 실행 완료를 구분하기
새 비동기 실행은 접수 응답을 반환합니다. 완료와 실패는 SSE 핸들러에서 별도로 드러나므로 HTTP 응답을 최종 결과로 오해하지 않도록 설명할 수 있습니다.
반복 요청에 같은 실행의 기준을 두기
공개 라우트에는 사용자·멱등성 키로 기존 실행을 찾고 재사용하는 분기가 있습니다. 코드에 이 분기가 있음을 확인한 것이며 동시 요청이나 exactly-once를 검증한 것은 아닙니다.
모델 선택을 확인할 수 있게 남기기
실행 표현에는 공급자 선택, 시도 이력, fallback 정보가 포함됩니다. 가상의 성공 화면 대신 관련 코드를 직접 연결했습니다.
03 / 예외 검토
경계에서 확인해야 할 질문.
실제 장애나 테스트 통과 결과가 아닌 검토용 시나리오입니다.
같은 실행 요청을 다시 보냈다면
- 처리 방식
- 기존 실행을 찾는 분기는 저장된 실행과 재사용 표시를 반환합니다.
- 확인할 내용
- 아래 원본 라우트에서 사용자·키 조회를 확인할 수 있습니다. 동시 요청과 저장소의 고유성 보장은 별도의 실행 검증 대상이며 이번에 테스트하지 않았습니다.
승인을 거절했거나 이미 결정됐다면
- 처리 방식
- 승인 API는 승인·거절을 받고, 저장소가 결과를 반환하지 않으면 대상 없음 또는 이미 결정된 상태로 응답합니다.
- 확인할 내용
- 결정 기록과 실행 권한 검사를 나눠 읽어야 합니다. 이 엔드포인트 하나만으로 전체 실행의 차단 정책을 추론하지 않습니다.
완료를 보기 전에 스트림이 닫혔다면
- 처리 방식
- SSE는 저장된 실행 상태를 조회하고 최종 상태나 시간 초과에 연결을 닫습니다. 실행을 다시 읽는 별도 엔드포인트도 있습니다.
- 확인할 내용
- 다시 상태를 조회할 수 있는 코드는 확인했습니다. 화면의 자동 재연결이나 모든 중간 이벤트 전달까지 확인한 것은 아닙니다.
구현 범위
JARVIS
Orchestrator Backend
API와 작업 흐름
- 미션·협의·실행 API
- 모델 선택 정책
- 역할별 승인과 작업 공간
HUD Frontend
운영자 인터페이스
- 시각 중심 화면과 모듈형 위젯
- 작업 공간과 승인 화면
- 미션 중심 탐색
Quality Loop
검증과 자체 사용
- OpenAPI 기반 클라이언트 타입
- 주요 흐름 E2E 검사
- 화면 근거를 포함한 검수 기록
사용 기술
- TypeScript
- Next.js
- Fastify
- PostgreSQL
- Zod
- Playwright
- React Three Fiber
- SSE
04 / 자료와 기록
설명의 근거를 확인합니다.
공개 저장소의 실행·승인 라우트와 회귀 검사 스크립트를 읽고 연결했습니다. 코드 확인을 전체 실행 검증이나 보안 인증으로 확대하지 않았습니다.
아래 링크는 설명용으로 다시 만든 코드가 아니라 e2e2ebf 커밋의 공개 원본입니다. 회귀 검사 스크립트는 읽기만 했으며 실행하지 않았습니다. 실제 실행 화면·성공 횟수·성능 결과를 새로 만들지 않았습니다.
공개 코드 · 고정된 커밋
실행 요청과 재사용 분기입력 검증, 사용자·키 조회, 비동기 실행 생성.실행 결과 스트림실행 조회, 최종 상태 이벤트와 SSE 종료 처리.승인 결정 핸들러승인 요청 생성과 승인·거절 결정 기록.회귀 검사 스크립트요청 프로필과 기능 기대값을 확인하는 코드. 통과한 실행 결과는 아닙니다.기존 상세 기록 펼치기
풀어야 했던 문제
모호한 요청을 조사·코드 실행·승인·자동화로 나누면서도 누가 무엇을 실행할 수 있는지, 현재 어느 단계인지 운영자가 이해할 수 있어야 했습니다.
설계와 구현
Fastify 백엔드에 역할별 인증, 모델 선택 정책, 미션·협의·실행·승인·메모리 API와 SSE 상태 전송을 구성했습니다. Next.js HUD에서 작업과 근거를 한 화면에 연결하고, OpenAPI 타입 동기화와 Playwright 검증을 추가했습니다.
개요
- 1인 개발로 진행한 개인용 AI 운영체제입니다.
- 오케스트레이션 백엔드와 HUD 스타일 오퍼레이터 인터페이스를 결합해, 작업 라우팅/승인/실행/근거 표시를 하나의 제품으로 구성했습니다.
백엔드 표면
1) 오케스트레이션 API
- auth, providers, assistant contexts, missions, councils, executions, workspaces, memory, approvals, reports, radar, upgrades, jarvis sessions 등의 Fastify route 모듈을 구성했습니다.
- role 기반 인증/세션 처리, rate limit, raw-body parsing, 오류 정규화를 포함합니다.
- mission/council/execution/assistant/dashboard/notification 업데이트를 SSE/event 스트림으로 제공합니다.
2) 실행/정책 제어
- provider routing policy, credential resolution, registry refresh, token/health worker를 포함합니다.
- workspace runtime의 PTY spawn/write/read/shutdown 엔드포인트를 구성했습니다.
- 고위험 액션은 approval gate와 notification channel을 통해 제어합니다.
프론트엔드 표면
1) HUD 인터페이스
- Inbox, Assistant, Council, Workbench, Tasks, Reports, Watchers, Dossier, Notifications, Skills, Approvals, Memory, Settings, Model Control, Ideation 모듈을 가진 Next.js HUD를 구성했습니다.
- visual core 페이지와 scene switching, widget 기반 네비게이션을 제공합니다.
- core, studio, mission, tasks, approvals, automations, settings, reports 등의 딥링크 라우트를 가집니다.
2) 타입/클라이언트 동기화
- OpenAPI 스펙에서 프론트 타입을 생성해 클라이언트 계층과 맞췄습니다.
- 위젯 간 API 요청/응답을 타입 기반으로 연결했습니다.
품질 루프
- core visibility, HUD intake autoplay, council trace, session restore, auth/settings에 대한 Playwright smoke 커버리지를 구성했습니다.
- 저장소 내부에 도그푸딩 리포트, 스크린샷, 검증 결과를 남겨 회귀와 품질 이력을 추적합니다.
- 공개 GitHub 저장소를 통해 코드와 검증 산출물을 직접 확인할 수 있습니다.