Files
lolympus-agent/plan.md
T
2026-05-12 08:16:31 -07:00

74 KiB
Raw Blame History

lolympus-agent 2026 Overhaul — Implementation Plan

Audience: 이 문서는 Codex(또는 다른 AI 에이전트)가 self-contained하게 작업할 수 있도록 작성됨. 모든 결정 사항, 파일 경로, 인터페이스, env/Redis 스키마, NATS subject 카탈로그, Phase별 산출물이 명시됨.


1. Executive Summary

목적: 카카오톡 오픈채팅 게임 커뮤니티(lolympus) 새내기 온보딩 Agent를 "인간 직원에 가까운 응답 품질"로 끌어올린다.

접근: 2026 AI agent 연구(Anthropic context engineering, OTel GenAI semconv, Reflection 패턴, Hermes/OpenAI tool calling, confidence-gated orchestration)를 적용해 6단계(Phase 0–5)로 광범위 개선.

최종 목표 지표:

  • p50 응답 latency < 800ms, p95 < 2.8s
  • Shadow eval LLM-judge 평균 점수 ≥ 4.0/5.0 유지
  • 온보딩 완료율 기준선 대비 유의미한 향상 (별도 측정)

총 추정 소요 (단일 개발자): 약 20–27일 (≈ 4–5.5주).


2. Current State (기존 시스템)

2.1 진입/통신

  • src/main.ts → NATS request/reply (subject lolympus-agent.request)
  • src/agent/agent.ts: request.skill 매칭된 Skill.handle() 호출
  • Request: {requestId, skill, chatroomId, userId, nickname, trigger, userMessage?, context?}
  • Response: {requestId, text, confidence, source: "llm"|"template", metadata?}

2.2 LLM

  • src/llm/llm-client.ts: 엔드포인트 체인 CLI_PROXY_API_URLS → AGENT_LLM_API_URLS → LLAMA_SERVER_API_URL
  • 모델: Qwen3.5-4B (로컬 llama-server)
  • 매 요청마다 /health check (5s timeout) — 병목
  • Function calling 미사용, 단일 system prompt + few-shot

2.3 Skill

  • 단일 OnboardingSkill. 7가지 trigger 라우팅 (new-member / nickname-invalid / photo-failed / progress-update / timeout-warning / completed / user-message) + default
  • 단일 거대 system prompt (약 1800 tokens)
  • 정규식 기반 의도 감지 (message-filter.ts): shouldSkipMessage, detectLightweightIntent, isRemainingStatusQuestion
  • 폴백 템플릿: onboarding-templates.ts (analyzeNicknameIssues, getNicknameInvalidMessage 등)
  • 응답 후처리: <think> 제거, URL 화이트리스트(discord/kakao), 마크다운 제거, 600자 절단
  • 저품질 감지: 길이 < 10자 또는 bigram 3회+ → temp +0.1 재시도

2.4 상태 저장

  • Garnet/Redis
    • 온보딩 세션 (lolympus 본체가 작성, agent는 read-only): lolympus:onboarding:{chatroomId}:{userId}
    • 대화 히스토리 (FIFO 20개, 12h TTL): lolympus-agent:conv:{chatroomId}:{userId}
  • MongoDB (dakao DB, events 컬렉션): RoomContextService가 최근 8개 메시지 조회

2.5 부재

  • 테스트 0건, eval set 0건
  • 메트릭/트레이싱 0 (console.log만)
  • 로깅 라이브러리, 린터 없음
  • Function calling 미사용
  • Feature flag, circuit breaker 없음

3. Target Architecture

NATS "lolympus-agent.request"
    │
    ▼
Agent.handleRequest
    │  AsyncLocalStorage(RequestContext) 개시, root OTel span
    ▼
OnboardingSkill.handle (skill.ts) — 이하 단계는 src/skills/onboarding/{state,prompts,runtime}/ 모듈들이 담당
    ├─ 1. classifier.classify(userMessage) → Intent (regex first, LLM fallback)
    ├─ 2. state.derive(session, trigger, intent) → DerivedState {phase, responseMode, tier, ...}
    │    • shouldRespond=false면 여기서 empty 반환
    ├─ 3. blackboard.load() + prompt.PromptBuilder.forDerived(derived, ctx).build()
    ├─ 4. orchestrator.run(derived, messages)
    │    • Tier 0 (~95%): single LLM call
    │    • Tier 1 (~4%): Planner → Responder
    │    • Tier 2 (~1%): Planner → Responder → Critic → Rewrite
    │    • LLM 호출 내부에 tool loop (max 2 hop) — Hermes XML + OpenAI JSON 양쪽 파싱
    ├─ 5. validator.check(response, derived) → pass | soft-warn | reject
    │    • reject → 템플릿 fallback
    ├─ 6. postProcess (URL/마크다운/길이)
    └─ 7. blackboard.update() + shadowBus.publish() (fire-and-forget)

병렬:
    OTel spans → stdout exporter (prod: 10% sampling)
    Pino logs → stdout (NODE_ENV별 level 분기)
    Background worker (별도 PM2 entry):
        • Redis Stream consumer: eval judging, conversation summarization
    Alert: 임계값 이상 → NATS "lolympus-agent.alert" → 본체가 KakaoTalk 발송

핵심 원칙

  1. agent.ts (NATS 레이어)는 ALS wrap만 추가. NATS 인터페이스 변경은 신규 subject 추가로만.
  2. 모든 개선은 Skill.handle 내부(src/skills/{name}/{state,prompts,runtime}/ 모듈들)에서. SkillRuntime이라는 별도 클래스는 없으며 "skill의 runtime 모듈군"의 통칭.
  3. 95% 트래픽은 fast path 1-hop. Tier 결정 = DerivedState.tier.
  4. LLM 호출 수 turn당 평균 1회 목표.
  5. 모든 시간은 UTC ISO-8601.

4. Resolved Decisions (모두 확정)

# 영역 결정
1 LLM provider 우선순위 모든 tier에서 CLIPROXY 최우선 → 실패 시 로컬 Qwen 폴백. 추후 CLIPROXY → OpenRouter → Qwen (OpenRouter는 구현만, OPENROUTER_ENABLED=false 기본 비활성)
2 CLIPROXY 사양 OpenAI-compatible API. JSON 모드 + tool calling 지원 확인됨. 사용 모델: 저지연 gpt-5.3-codex-spark, 고성능 gpt-5.4, LLM-judge용 gpt-5.3-codex-spark
3 Tier별 모델 매핑 Tier 0: gpt-5.3-codex-spark; Tier 1 Planner: gpt-5.4, Responder: gpt-5.3-codex-spark; Tier 2 Critic/Rewrite: gpt-5.4. 모두 CLIPROXY 경유. 실패 시 각각 로컬 Qwen으로 폴백
4 로깅 정책 PII 마스킹 X. NODE_ENV별 level: dev=trace, test=debug, prod=warn. prod OTel sampling 10%. Infisical KNOWN_SECRET_KEYS 값은 redact
5 Timezone 모든 timestamp UTC ISO-8601. 프롬프트 표시만 Asia/Seoul 변환
6 본체 계약 변경 자유 — 새 trigger, context 필드, NATS subject 추가 적극 활용
7 Shadow worker 배포 별도 PM2 entry (ecosystem.config.js). 단일 worker가 eval judging + conversation summarization 모두 처리 (lolympus-agent:background Redis Stream consumer group)
8 Garnet 키 네임스페이스 lolympus-agent:*. 본체의 lolympus:*와 분리. 자료구조는 §8 참조
9 Alert lolympus-agent.alert NATS subject. 본체가 KakaoTalk 발송. 자동 rollback 없음 — 알림만, 사용자 승인 후 수동 revert
10 Rollout v2 직진 cutover — feature flag 없음, v1 alias 없음. PR 단위로 갈아치움
11 onboarding-templates.ts Phase 5 안정화 후 deprecated. validator reject 시 fallback으로 그동안 재사용
12 Golden set Phase 2 완료 후 사용자가 npm run eval:capture로 MongoDB events에서 추출. expected 직접 큐레이션. 규모 30–50건
13 Property test v1↔v2 비교 생략. 핵심 불변식 5–10개만 unit test
14 Phase별 smoke test Phase 3/4 끝마다 npm run eval 실행(규칙+golden set). Phase 5에서 shadow eval 본격 가동

DX 결정

  • 디렉토리: Feature-first + tsconfig paths (@agent/*, @skills/*, @llm/*, @obs/*, @eval/*, @tools/*, @common/*, @conv/*, @room/*)
  • Types colocated: 각 feature 폴더 내 types.ts (기존 *-types.ts 통합)
  • 테스트: Vitest + fast-check, *.test.ts colocated, coverage @vitest/coverage-v8
    • Redis 의존 부분은 ioredis-mock으로 in-memory. integration 테스트 별도 경로 불필요 (단일 개발자 환경, 운영 부하 수준에서 Redis 자체 버그 희귀)
    • MongoDB 의존 코드 (room-context, eval:capture)는 unit test 대상 외 — service interface를 mock하는 방식으로만 테스트. eval:capture는 수동 실행이라 CI 대상 아님
    • vitest.setup.ts 신설: pino silent, OTel noop exporter, ioredis-mock 전역 주입. 주입 방식 — 파일 상단에서:
      import { vi } from "vitest";
      vi.mock("ioredis", async () => {
        const RedisMock = (await import("ioredis-mock")).default;
        return { default: RedisMock, Redis: RedisMock };
      });
      
      vitest.config.ts에 test.setupFiles: ["./vitest.setup.ts"] 등록. Redis를 직접 new Redis(...)로 생성하는 코드는 모두 자동으로 ioredis-mock 인스턴스 반환 — Stream 포함 동작 지원 확인됨 (XADD/XREADGROUP/XACK/XCLAIM)
  • 린트/포맷: ESLint flat config (typescript-eslint recommended-type-checked) + Prettier 3 + tsc strict. PR gate
  • Skill 내부: src/skills/onboarding/{state,prompts,runtime}/ 서브디렉토리 (§5.5)

5. File Map

5.1 신규

src/
├── observability/                        [Phase 0]
│   ├── logger.ts                         pino + NODE_ENV 기반 level + Infisical secret redaction
│   ├── tracing.ts                        OTel SDK init, stdout exporter, prod 10% sampling
│   ├── spans.ts                          withLlmSpan, withToolSpan, withSkillSpan, withClassifierSpan
│   ├── context.ts                        AsyncLocalStorage<RequestContext>
│   ├── alert.ts                          [Phase 5] 임계값 초과 시 NATS "lolympus-agent.alert" publish
│   └── types.ts
│
├── llm/
│   ├── circuit.ts                        [Phase 1] endpoint별 상태 (healthy/unhealthy/open), 30s 캐시, 연속 실패 N회 cooldown
│   ├── routing.ts                        [Phase 5] tier → provider 우선순위 결정
│   ├── providers/
│   │   ├── cliproxy.ts                   OpenAI-compatible, JSON/tool 지원
│   │   ├── llama.ts                      llama.cpp, Hermes prompt로 JSON 강제
│   │   └── openrouter.ts                 구현만, OPENROUTER_ENABLED gate
│   └── types.ts                          (기존 llm-types.ts를 통합)
│
├── skills/onboarding/
│   ├── skill.ts                          [Phase 2 개명] 진입점 (기존 onboarding-skill.ts를 git mv)
│   ├── index.ts                          [Phase 2] barrel export (§5.5)
│   ├── constants.ts                      [Phase 4] 규칙 상수 SoT (VALID_TIERS, HEART_RULE_TEXT 등 + env wrapper)
│   ├── types.ts                          (기존 onboarding-types.ts 통합)
│   ├── state/                            [Phase 2]
│   │   ├── onboarding-state.ts           OnboardingPhase / Intent discriminated union
│   │   ├── derive.ts                     derive(session, trigger, intent): DerivedState (pure)
│   │   ├── transitions.ts                phase 전이 테이블 (현재는 session 필드 기반이라 얇음)
│   │   ├── classifier.ts                 regex first + LLM JSON fallback
│   │   ├── intent-keywords.ts            intent → 기대 키워드 사전 (validator에서 사용)
│   │   └── blackboard.ts                 [Phase 3] Redis conv working memory
│   │
│   ├── prompts/                          [Phase 3]
│   │   ├── layers.ts                     persona / policy / state / examples / context 5-layer
│   │   ├── examples.ts                   Record<Intent["kind"], Example[]> few-shot bank
│   │   ├── builder.ts                    PromptBuilder.forDerived(derived, ctx).build()
│   │   └── tool-policy.ts                [Phase 4] buildToolPolicy(intent, phase) — tool 사용 시나리오 가이드
│   │
│   └── runtime/                          [Phase 4–5]
│       ├── orchestrator.ts               [Phase 5] tier 0/1/2 분기 + 모델 매핑 실행
│       ├── planner-schema.ts             [Phase 5] PlannerOutput zod schema (§9.5.1.1)
│       ├── tool-loop.ts                  [Phase 4] tool call 감지 → 실행 → tool_result append → 재호출 (max 2 hop)
│       ├── validator.ts                  [Phase 4] postProcess + state 모순 / self-consistency / intent 매칭 검사
│       └── critic.ts                     [Phase 4 정의 / Phase 5 orchestrator 통합] tier 2 전용 self-critique
│
├── tools/                                [Phase 4]
│   ├── tool.ts                           Tool<TArgs, TResult> 인터페이스 + zod
│   ├── registry.ts                       Tool 등록/조회
│   ├── parser.ts                         Hermes <tool_call>...</tool_call> + OpenAI tool_calls 양쪽 파싱
│   ├── serializer.ts                     tool 선언을 system prompt에 주입할 포맷(Hermes spec 준수)
│   └── builtins/
│       ├── validate-nickname.ts          analyzeNicknameIssues 래핑
│       ├── check-onboarding-progress.ts  session → 구조화 요약
│       ├── lookup-community-rule.ts      나이 27+, 티어 코드, 디스코드 링크 등
│       └── get-room-context.ts           RoomContextService 래핑, LLM 호출 시만 조회
│
├── eval/                                 [Phase 5]
│   ├── golden/
│   │   └── onboarding.jsonl
│   ├── judges/
│   │   ├── rule-judge.ts                 validator + must-include/exclude 매칭
│   │   └── llm-judge.ts                  CLIPROXY gpt-5.3-codex-spark로 1-5점 (친근/정확/간결/범위)
│   ├── runner.ts                         golden set 실행
│   ├── shadow-bus.ts                     Redis Stream publish (fire-and-forget <5ms)
│   ├── shadow-worker.ts                  consumer 로직 (workers/background.ts PM2 entry가 기동)
│   ├── capture.ts                        MongoDB events에서 실제 케이스 추출하는 helper
│   ├── anonymize.ts                      [Phase 2] capture 파이프라인 익명화 (§9.2.5, 강제 단계)
│   └── cli.ts                            npm run eval / eval:capture 엔트리
│
├── conversation/
│   └── summarizer.ts                     [Phase 3] 5턴 초과 오래된 절반 요약. shadow-worker가 consume
│
├── workers/                              [Phase 5]
│   └── background.ts                     shadow-worker.ts + summarizer consumer를 하나의 PM2 entry로 묶음
│
└── common/
    └── nats-subjects.ts                  모든 NATS subject 상수 + 타입 (§7 참조)

5.2 수정

  • src/main.ts — bootstrap 순서에 initTracing(), initLogger() 최상위 추가
  • src/agent/agent.ts — runWithContext(ctx, () => ...)(§9.1.2의 context.ts 헬퍼)로 handleRequest 전체 wrap, root span 생성, 응답 후 shadowBus.publish
  • src/llm/llm-client.ts — chatCompletion(messages, opts: ChatCompletionOpts) 시그니처(상세 타입은 §9.5.2 참조, signal/deadlineMs/maxTokens/role/modelOverride/temperature 포함). 내부에서 withLlmSpan + circuit breaker + tier→provider 라우팅. health check는 circuit.ts에서 조회
  • src/skills/onboarding/onboarding-skill.ts → skill.ts로 개명(§5.4/§5.5, Phase 2 PR 2a에서 git mv) + handle 재작성. 얇은 진입점으로. classifier → derive → orchestrator 위임
  • src/conversation/conversation-store.ts — summary slot 추가. 5턴 초과 시 Redis Stream lolympus-agent:background에 {type:"summarize", chatroomId, userId} 발행
  • src/config.ts — tier별 model / maxTokens / temperature getter, OpenRouter 관련 env, ALERT_THRESHOLD_* 추가
  • src/common/secret-manager.ts — redact 대상 키 리스트 export (logger에서 사용)
  • tsconfig.json — paths 추가
  • package.json — 의존성 + scripts
  • launch-server.ps1 — pm2 start ecosystem.config.js --only agent,agent-worker 기반으로 단순화 (Windows 호환 유지)

5.3 신설 (루트)

  • ecosystem.config.js — PM2 설정. 2 process: agent(main), agent-worker(background)
  • vitest.config.ts — paths alias 동기화, 커버리지
  • eslint.config.js — flat config. no-restricted-imports로 @skills/onboarding/runtime/* 외부 import 차단
  • .prettierrc
  • .editorconfig
  • .gitignore 신설/갱신 — eval-reports/, *.tsbuildinfo, coverage/, dist/, .env* 추가

5.4 Deprecate (v2 직진 — 삭제 시점은 Phase별 상이)

  • src/skills/onboarding/message-filter.ts → PR 2a에서 @deprecated 표시 + classifier 내부에서 일시 재사용 → PR 2b에서 삭제 (golden set 통과 후)
  • src/skills/onboarding/onboarding-prompts.ts → PR 2a에서 @deprecated 표시 + 인라인 유지 → Phase 3 PR에서 builder 도입과 함께 삭제
  • src/skills/onboarding/onboarding-templates.ts → Phase 5 안정화 이후 삭제. 그 전까지 validator reject fallback
  • src/skills/onboarding/onboarding-skill.ts → Phase 2에서 src/skills/onboarding/skill.ts로 개명(파일 내용은 handle 재작성과 함께). 개명 이유는 §5.5 참조

5.5 파일 구조 (skill별 분리)

진입점은 폴더 최상위, 내부 구현은 서브디렉토리 — 각 skill이 자체 runtime/state/prompts 를 가짐. 향후 game-analysis 등 skill 추가 시 동일 패턴.

src/skills/
├── skill.ts                          # Skill 인터페이스(공통)
├── registry.ts                       # skill 등록/조회 (skill이 2+개 되면 신설)
└── onboarding/
    ├── skill.ts                      # OnboardingSkill (진입점, Phase 2에서 onboarding-skill.ts를 개명)
    ├── index.ts                      # barrel: export { OnboardingSkill } from "./skill"
    ├── constants.ts                  # SoT 상수 (나이, 티어, 데드라인 등)
    ├── types.ts                      # OnboardingSession, NicknameIssue 등 skill-local 타입
    ├── state/                        # Phase 2: classifier, derive, transitions, blackboard
    ├── prompts/                      # Phase 3: layers, examples, builder, (Phase 4) tool-policy
    └── runtime/                      # Phase 4~5: orchestrator, tool-loop, validator, critic, planner-schema

외부 import는 import { OnboardingSkill } from "@skills/onboarding" 단일 경로. runtime/*은 skill-internal (외부 import 금지 — eslint 규칙으로 @skills/onboarding/runtime/* import 차단).


6. Env Variables Catalog

env-vars/{dev,test,prod}.env 공통. 시크릿은 Infisical.

6.1 기존 (유지)

  • NODE_ENV — dev | test | prod
  • SERVICE_NAME — 기본 lolympus-agent
  • NATS_ENDPOINT, NATS_USER, NATS_PASS
  • GARNET_ENDPOINT, GARNET_USERID, GARNET_PASSWORD
  • MONGODB_CONNECTION_STRING, MONGODB_PROJECT_ID
  • CLI_PROXY_API_URLS (newline 또는 comma 분리)
  • AGENT_LLM_API_URLS, LLAMA_SERVER_API_URL

6.2 신규

Key 기본값 설명
LOG_LEVEL NODE_ENV별 기본 명시 시 override
OTEL_SAMPLING_RATIO dev/test=1.0, prod=0.1 OTel trace sampling
OTEL_EXPORTER stdout 향후 otlp로 전환 가능
LLM_HEALTH_CACHE_TTL_MS 30000 circuit breaker 캐시
LLM_CIRCUIT_FAILURE_THRESHOLD 3 연속 실패 횟수
LLM_CIRCUIT_COOLDOWN_MS 60000 개방 후 쿨다운
TIER0_MODEL gpt-5.3-codex-spark
TIER1_PLANNER_MODEL gpt-5.4
TIER1_RESPONDER_MODEL gpt-5.3-codex-spark
TIER2_CRITIC_MODEL gpt-5.4
TIER0_MAX_TOKENS 384
TIER1_MAX_TOKENS 512 Responder 출력 상한
TIER2_MAX_TOKENS 512 Rewrite 출력 상한
PLANNER_MAX_TOKENS 256 Tier 1 Planner JSON 출력 상한
CRITIC_MAX_TOKENS 512 Tier 2 Critic 출력 상한
CLASSIFIER_FALLBACK_MODEL gpt-5.3-codex-spark 경량 intent classify
CLASSIFIER_BUDGET_MS 200 classifier LLM fallback 허용 시간. deadline에서 차감
CLASSIFIER_MAX_TOKENS 16 intent JSON만 받으므로 매우 작게
LLM_JUDGE_MODEL gpt-5.3-codex-spark Phase 5 shadow eval judge
LLM_JUDGE_MAX_TOKENS 128 4축 점수 + 한줄 이유
EVAL_PROCESS_LLM_JUDGE_ENABLED false Phase 7 shadow-worker process judge LLM 보조 평가 활성화
EVAL_PROCESS_LLM_JUDGE_SAMPLING_RATE 0.1 Phase 7 process LLM judge sampling rate
EVAL_PROCESS_LLM_JUDGE_MAX_TOKENS 256 Phase 7 process LLM judge 출력 상한
SAFETY_MARGIN_MS 500 NATS 5s timeout에서 차감 (§7)
TIER0_ESTIMATED_CALL_MS 600 deadline 계산용
TIER1_ESTIMATED_CALL_MS 1200
TIER2_ESTIMATED_CALL_MS 1400
ESCALATION_BUDGET_PER_TURN 2 §9.4.6 escalation 추가 호출 상한
DEADLINE_NEAR_THRESHOLD_MIN 30 §9.2 constants. 데드라인 ≤ 30분 시 phase=deadline-near
EVAL_ANON_SALT (env 아님) env 등록 X — src/eval/anonymize.ts 상단에 const EVAL_ANON_SALT = "lolympus-agent-v1"로 하드코딩(§9.2.5). 값 변경 시 golden set 해시 불일치 → env로 빼면 의도치 않은 override 위험
OPENROUTER_ENABLED false Phase 5 구현만, 기본 비활성
OPENROUTER_API_URL https://openrouter.ai/api/v1
OPENROUTER_API_KEY — Infisical
OPENROUTER_TIER1_MODEL openai/gpt-5.3-codex-spark
OPENROUTER_TIER2_MODEL openai/gpt-5.4
SHADOW_EVAL_SAMPLING_RATE_TIER0 prod=0.1, dev=1.0 tier 0 응답 sampling (트래픽 95%라 낮게)
SHADOW_EVAL_SAMPLING_RATE_TIER1 prod=0.5, dev=1.0 tier 1 응답 sampling (트래픽 4%라 높게)
SHADOW_EVAL_SAMPLING_RATE_TIER2 prod=1.0, dev=1.0 tier 2 응답 sampling (트래픽 1%라 100%)
ALERT_THRESHOLD_P95_LATENCY_MS 3000 초과 시 KakaoTalk alert
ALERT_THRESHOLD_EVAL_SCORE_DROP_PCT 10 baseline 대비 하락률
ALERT_THRESHOLD_LLM_ERROR_RATE 0.1 1분 윈도우 에러율
ALERT_THRESHOLD_DRIFT_PCT 15 Phase 6 24h vs 7d slice 점수 하락률
ALERT_RATE_LIMIT_SEC 300 동일 종류 알림 재발송 최소 간격
BLACKBOARD_TTL_SEC 43200 12h
CONVERSATION_SUMMARY_TTL_SEC 86400 24h
EVAL_STREAM_MAXLEN 10000 Redis Stream MAXLEN ~
EVAL_RESULTS_TTL_SEC 2592000 30일
EVAL_AGG_TICK_MS 300000 Phase 6 slice aggregator tick
EVAL_AGG_TTL_SEC 604800 Phase 6 slice Hash TTL
EVAL_AGG_LATENCY_SAMPLE_CAP 200 Phase 6 p50/p95 계산용 latency sample cap
EVAL_ARCHIVE_TICK_MS 3600000 Phase 6 Redis eval stream → Mongo archive tick
EVAL_ARCHIVE_TTL_DAYS 30 Phase 6 eval_archive.evaluatedAt TTL index
EVAL_ARCHIVE_BATCH_SIZE 500 Phase 6 archive tick당 stream entry 처리 수
EVAL_DRIFT_TICK_MS 86400000 Phase 6 drift detection tick
EVAL_PROMOTE_TICK_MS 86400000 Phase 6 golden candidate promotion tick
EVAL_PROMOTE_LOW_SCORE 2 Phase 6 low-score candidate 임계
EVAL_PROMOTE_RARE_THRESHOLD 5 Phase 6 rare-slice candidate 임계
EVAL_PROMOTE_PER_CATEGORY_LIMIT 10 Phase 6 promotion 카테고리별 최대 후보 수
EVAL_REVIEW_TICK_MS 300000 Phase 8 review-routing tick
EVAL_REVIEW_QUEUE_MAXLEN 500 Phase 8 review queue Stream MAXLEN
EVAL_REVIEW_LABEL_MAXLEN 5000 Phase 8 labeled Stream MAXLEN
EVAL_REVIEW_PER_CATEGORY_LIMIT 5 Phase 8 tick당 카테고리별 enqueue 한도
EVAL_REVIEW_DEDUPE_TTL_SEC 604800 Phase 8 review enqueue dedupe TTL
EVAL_CALIBRATION_MIN_CORR 0.5 Phase 8 사람/LLM calibration 최소 상관
REVIEWER_ID git user.email fallback Phase 8 review CLI reviewedBy 식별자
LLM_PROPOSE_MODEL LLM_JUDGE_MODEL Phase 9 propose 단계 모델
LLM_PROPOSE_MAX_TOKENS 1024 Phase 9 proposal JSON 출력 상한
EVAL_TOURNAMENT_MAX_MATCHES 50 Phase 9 tournament 최대 match 수
EVAL_TOURNAMENT_MIN_CASES 10 Phase 9 propose/tournament 최소 archive case 수
PROMPT_VARIANT_ID — Phase 9 운영 prompt variant manifest 적용
BACKGROUND_STREAM_MAXLEN 5000

7. NATS Subject Catalog

src/common/nats-subjects.ts에 상수 + 타입으로 정의.

Subject 방향 Payload 설명
lolympus-agent.request in AgentRequest 기존. lolympus 본체 → agent. timeout 5000ms (본체 NATS request timeout, 본체 측 PR로 명시)
lolympus-agent.alert out AlertPayload 신규. agent → lolympus 본체 (본체가 KakaoTalk 발송)
lolympus-agent.eval.report out (optional) EvalReport 신규. 배치 eval 결과 publish. 본체가 대시보드로 수집 가능

Deadline budget propagation (timeout 마진 운영):

  • Agent.handleRequest 진입 시 deadlineAt = now + 5000ms - SAFETY_MARGIN_MS(기본 500ms) = +4500ms. ALS context에 저장.
  • Classifier LLM fallback도 budget 차감 대상: regex unknown → LLM fallback 호출 시 CLASSIFIER_BUDGET_MS(기본 200ms) 차감 확인. 여유 없으면 classifier fallback 생략하고 intent=unknown으로 진행(derive가 tier 0 / responseMode=llm으로 처리).
  • Orchestrator는 각 LLM 호출 전 if (now > deadlineAt - estimatedCallMs) { degrade(); } 체크.
    • tier 2 escalation 직전에도 동일 체크 → deadline 부족하면 escalation 포기
  • chatCompletion에 signal: AbortController.signal로 deadline-aware timeout 전달. AbortError → validator reject → 템플릿 fallback
  • tier별 estimatedCallMs(env override 가능): tier0=600, tier1=1200, tier2=1400. 운영 측정 후 조정

AlertPayload 예시:

interface AlertPayload {
  kind:
    | "archive-stalled"
    | "endpoint-down"
    | "eval-drift"
    | "eval-score-drop"
    | "latency"
    | "llm-error-rate";
  severity: "info" | "warn" | "critical";
  metric: string;
  value: number;
  threshold: number;
  window: string;       // e.g. "5m"
  traceId?: string;
  timestamp: string;    // UTC ISO
  suggestedAction?: string;
}

lolympus 본체 측 변경: lolympus-agent.alert 구독자 추가해 운영 채팅방(관리자 전용)에 카톡으로 발송.


7.1 OTel Attribute 표준

span/log 일관성 위해 커스텀 attribute는 아래 네이밍만 사용. dashboard 쿼리 작성 시 예측 가능.

Attribute 타입 범위 설명
gen_ai.system string LLM span 표준 semconv. 값: "cliproxy" | "llama" | "openrouter"
gen_ai.request.model string LLM span 표준 semconv
gen_ai.usage.input_tokens int LLM span 표준 semconv
gen_ai.usage.output_tokens int LLM span 표준 semconv
gen_ai.response.finish_reasons string[] LLM span 표준 semconv
agent.request_id string root AgentRequest.requestId
agent.chatroom_id string root
agent.user_id string root
agent.skill string root 예: "onboarding"
agent.trigger string root AgentRequest.trigger
agent.intent string skill span Intent["kind"]
agent.phase string skill span OnboardingPhase["kind"]
agent.response_mode string skill span "skip" | "template" | "llm" | "llm-with-tools"
agent.tier.initial int skill span derived.tier
agent.tier.final int skill span escalation 후 최종 tier
agent.tier.escalated_from int escalation event
agent.tier.escalated_to int escalation event
agent.validator.status string skill span "pass" | "soft-warn" | "reject"
agent.validator.warnings string[] skill span 감지된 rule 이름 배열
agent.tool.name string tool span
agent.tool.hop int tool span 현 turn 내 hop number (0-indexed)
agent.tool.result_valid bool tool span zod result schema 통과 여부
agent.deadline.remaining_ms int skill span 종료 시 음수면 초과
agent.source string root response "llm" | "template" | "empty"
agent.classifier.source string classifier span "regex" | "llm"
agent.classifier.confidence float classifier span 0-1

커스텀 attribute 네임스페이스는 항상 agent.*. OTel 표준 영역은 gen_ai.* 그대로 사용. 다른 네임스페이스 신설 금지.


8. Garnet/Redis Key Schema

Key Pattern Type TTL 설명
lolympus:onboarding:{chatroomId}:{userId} String (JSON) 본체 관리 본체 소유, agent read-only
lolympus-agent:conv:{chatroomId}:{userId} String (JSON array) 12h 대화 히스토리 FIFO 20 (기존)
lolympus-agent:summary:{chatroomId}:{userId} String 24h Phase 3 대화 요약 slot
lolympus-agent:bb:{chatroomId}:{userId} String (JSON) 12h Phase 3 Blackboard
lolympus-agent:circuit:{endpointHash} Hash no TTL Phase 1 circuit breaker 상태
lolympus-agent:background Stream MAXLEN ~ $BACKGROUND_STREAM_MAXLEN (기본 5000) Phase 5 background jobs (eval/summary). Consumer group: bg-worker
lolympus-agent:background:dlq Stream MAXLEN ~ 1000 (리터럴, 작은 값이라 env 미등록) Phase 5 dead-letter. retry 실패 시 XADD. 수동 조사용
lolympus-agent:eval:results Stream MAXLEN ~ $EVAL_STREAM_MAXLEN (기본 10000) Phase 5 shadow eval 결과
lolympus-agent:eval:baseline String (JSON) no TTL Phase 5 최근 안정 baseline 점수
lolympus-agent:eval:agg:{tier}:{intent}:{phase} Hash $EVAL_AGG_TTL_SEC Phase 6 slice별 count/score/validator/latency metric
lolympus-agent:eval:agg:cursor String no TTL Phase 6 마지막 aggregated eval stream id
lolympus-agent:eval:archive:cursor String no TTL Phase 6 마지막 Mongo archived eval stream id
lolympus-agent:eval:review:queue Stream MAXLEN ~ $EVAL_REVIEW_QUEUE_MAXLEN Phase 8 사람 검토 대기 큐. Consumer group: reviewers
lolympus-agent:eval:review:labeled Stream MAXLEN ~ $EVAL_REVIEW_LABEL_MAXLEN Phase 8 사람 라벨 적립 Stream
lolympus-agent:eval:review:dedupe:{evalStreamId} String $EVAL_REVIEW_DEDUPE_TTL_SEC Phase 8 동일 eval result 중복 검토 라우팅 방지
lolympus-agent:eval:review:cursor String no TTL Phase 8 마지막 review-routed eval stream id
lolympus-agent:eval:review:label-archive:cursor String no TTL Phase 8 마지막 Mongo archived review label stream id
lolympus-agent:metrics:tier:{YYYYMMDDHH} Hash 7일 tier 0/1/2 분포 카운터 (시작/최종 tier, escalation 카운트 포함)
lolympus-agent:metrics:escalation:{YYYYMMDDHH} Hash 7일 tier escalation from→to 카운트
lolympus-agent:alert:dedupe:{kind} String ALERT_RATE_LIMIT_SEC 동일 알림 rate limit
lolympus-agent:alert:dedupe:endpoint:{endpointHash} String ALERT_RATE_LIMIT_SEC endpoint-down 알림 per-endpoint rate limit
lolympus-agent:alert:dedupe:eval-drift:{tier}:{intent}:{phase} String ALERT_RATE_LIMIT_SEC Phase 6 drift alert per-slice rate limit
lolympus-agent:alert:dedupe:archive-stalled String ALERT_RATE_LIMIT_SEC Phase 6 archive failure alert rate limit

9. Phase별 작업 명세

Phase 0 — DX Infrastructure (1일)

목표: 이후 모든 phase의 기반. PR로 단독 머지 가능.

작업

  1. package.json 의존성 추가
    • runtime: pino, @opentelemetry/api, @opentelemetry/sdk-node, @opentelemetry/auto-instrumentations-node, @opentelemetry/semantic-conventions, zod
    • dev: pino-pretty, vitest, fast-check, @vitest/coverage-v8, eslint, @typescript-eslint/parser, @typescript-eslint/eslint-plugin, prettier, eslint-config-prettier, @types/node
    • scripts: test, test:watch, test:coverage, lint, lint:fix, format, typecheck, eval, eval:capture
  2. tsconfig.json에 paths: @agent/*→src/agent/*, @skills/*→src/skills/*, @llm/*→src/llm/*, @obs/*→src/observability/*, @eval/*→src/eval/*, @tools/*→src/tools/*, @common/*→src/common/*, @conv/*→src/conversation/*, @room/*→src/room-context/*
  3. vitest.config.ts (paths alias 동기화), eslint.config.js (flat config, type-checked rules), .prettierrc (print-width 100, single-quote), .editorconfig
  4. 기존 *-types.ts 파일을 각 feature 폴더 types.ts로 이동
    • src/agent/agent-types.ts → src/agent/types.ts
    • src/llm/llm-types.ts → src/llm/types.ts
    • src/room-context/room-context-types.ts → src/room-context/types.ts
    • src/skills/onboarding/onboarding-types.ts → src/skills/onboarding/types.ts
  5. 모든 import를 alias로 치환 + barrel index.ts 추가(feature별 공개 API 명시)

검증

  • npm run typecheck && npm run lint && npm run build 통과
  • npm start:dev로 부팅 성공 (기능 변경 없음 확인)

Phase 1 — Foundation (Observability + Health 캐싱) (2–3일)

목표: 측정 가능성 확보 + 매 요청 health check 제거로 즉시 latency 절감.

작업

1.1 Pino logger + NODE_ENV 분기 + secret redaction

  • 신규 src/observability/logger.ts:
    • 기본 level: dev=trace, test=debug, prod=warn (env LOG_LEVEL override)
    • transport: dev/test=pino-pretty, prod=JSON stdout
    • redact: ['req.headers.authorization', ...KNOWN_SECRET_KEYS.map(k=>\req.body.${k}`), ...]`
    • secret-manager.ts에서 KNOWN_SECRET_KEYS를 export해 import
    • logger.child({requestId, chatroomId, userId}) 헬퍼
  • 전 파일 console.* → logger.*로 치환 (grep + 수동)

1.2 OpenTelemetry SDK

  • 신규 src/observability/tracing.ts:
    • NodeSDK 초기화 (stdout span exporter)
    • @opentelemetry/auto-instrumentations-node 활성 (http, nats, ioredis 자동 계측)
    • prod: ParentBasedSampler(TraceIdRatioBasedSampler(0.1))
  • 신규 src/observability/spans.ts:
    • withSpan<T>(name, attrs, fn) 기본 헬퍼
    • withLlmSpan(op, attrs, fn): OTel GenAI semconv attribute 기록 (gen_ai.system, gen_ai.request.model, gen_ai.usage.input_tokens/output_tokens, gen_ai.response.finish_reasons)
    • withToolSpan(toolName, args, fn), withSkillSpan, withClassifierSpan
  • 신규 src/observability/context.ts: AsyncLocalStorage<RequestContext> + getContext(), runWithContext()

1.3 Circuit breaker

  • 신규 src/llm/circuit.ts:
    • 각 endpoint key → { state: "healthy"|"unhealthy"|"open", lastCheckedAt, failureCount, openedAt }
    • Redis Hash lolympus-agent:circuit:{endpointHash} + 로컬 LRU cache
    • canUse(endpoint): boolean, recordSuccess(endpoint), recordFailure(endpoint)
    • health check는 LRU TTL(30s) 초과시에만. cooldown 기간이면 canUse=false

1.4 main/agent wiring

  • src/main.ts: initTracing() → initLogger() → 기존 부트스트랩
  • src/agent/agent.ts:handleRequest: 전체를 runWithContext(ctx, async () => withSpan("agent.handle", {requestId, skill}, ...))로 wrap
  • src/llm/llm-client.ts:chatCompletion:
    • 엔드포인트 루프 시작 전 circuit.canUse(ep) 체크
    • 요청 부분을 withLlmSpan으로 감싸고 response에서 usage 추출해 span attribute로
    • 성공/실패 시 circuit.record* 호출

검증

  1. 부팅 → stdout에 OTel span JSON + pino pretty log
  2. 부하: 100 req 발사 → circuit:* Hash에서 lastCheckedAt 업데이트가 30s에 한 번 정도만 발생
  3. 고의로 endpoint를 kill → 3회 실패 후 state: "open" 전환, 60s 후 half-open 시도

Phase 2 — State Machine + Intent Classifier (3–4일)

목표: 흩어진 분기 로직을 순수 함수로 통합. 테스트 가능.

PR 분할 (회귀 위험 완화): Phase 2를 2개 PR로 쪼갠다. golden set이 없는 시점에 v1 코드를 일괄 삭제하면 회귀를 잡을 방법이 없음.

  • PR 2a: state/, classifier.ts, eval/capture.ts 신규 추가 + OnboardingSkill.handle을 derive/classifier로 교체. 단, message-filter.ts/onboarding-prompts.ts는 deprecated 표시(@deprecated JSDoc)만 하고 삭제하지 않음. classifier 내부에서 message-filter 함수를 재사용해 동작 동일성 확보.
  • PR 2a 머지 후: 사용자가 npm run eval:capture 실행 → §2.5 익명화 파이프라인 통과 → 30–50건 expected 수동 큐레이션 → src/eval/golden/onboarding.jsonl 커밋(별도 PR).
  • PR 2b: golden set 기반 npm run eval 통과 확인 후 message-filter.ts 삭제. onboarding-prompts.ts는 Phase 3 PR에서 builder 도입과 함께 삭제(Phase 3까지 임시 인라인 prompt 유지 허용 정책 그대로).
  • 이 분할은 v2 직진 원칙을 어기지 않음(feature flag 없음, alias 없음). 단순히 "삭제 시점"을 golden set 확보 직후로 미루는 것.

작업

2.1 State/Intent 타입

  • src/skills/onboarding/types.ts에 skill-local 타입 집중 (§5.5 구조):
    • OnboardingSession (기존 onboarding-types.ts 통합)
    • NicknameIssue 신규: { kind: "missing-tier" | "invalid-age" | "missing-gender" | "wrong-separator" | "unknown-tier" | "other"; message: string; suggestion?: string }
    • Example, PromptContext 등 prompts에서 쓰는 공용 타입도 여기 (Phase 3에서 추가)
    • Blackboard 타입(§9.3.2)도 여기로 이동
  • 신규 src/skills/onboarding/state/onboarding-state.ts:
    export type OnboardingPhase =
      | { kind: "fresh" }
      | { kind: "nickname-pending"; current: string }
      | { kind: "photo-pending" }
      | { kind: "both-pending" }
      | { kind: "nickname-rejected"; current: string; issues: NicknameIssue[] }
      | { kind: "photo-rejected"; reason?: string }
      | { kind: "deadline-near"; remaining: ("nickname" | "photo")[] }
      | { kind: "completed" }
      | { kind: "timed-out" };
    
    export type Intent =
      | { kind: "greeting" } | { kind: "acknowledgement" }
      | { kind: "status-question" } | { kind: "help-how" } | { kind: "help-where" }
      | { kind: "nickname-question" } | { kind: "photo-question" }
      | { kind: "discord-question" } | { kind: "age-question" }
      | { kind: "chitchat" } | { kind: "off-topic-to-other" } | { kind: "unknown" };
    
    export interface DerivedState {
      phase: OnboardingPhase; intent: Intent;
      shouldRespond: boolean;
      responseMode: "skip" | "template" | "llm" | "llm-with-tools";
      suggestedMaxTokens: number;
      allowShortResponse: boolean;
      tier: 0 | 1 | 2;
    }
    

2.2 derive (pure function)

  • 신규 src/skills/onboarding/state/derive.ts
  • 입력: (session | null, trigger, intent)
  • 출력: DerivedState. 규칙:
    • trigger=new-member → shouldRespond=false (본체가 템플릿 발송)
    • intent=off-topic-to-other|chitchat → shouldRespond=false
    • intent=greeting|acknowledgement → responseMode=template, tier 0
    • phase=nickname-rejected → responseMode=llm-with-tools, tier 1
    • phase=deadline-near → responseMode=llm, tier 1 (중요도 ↑)
    • 그 외 user-message → responseMode=llm, tier 0
  • src/skills/onboarding/state/transitions.ts: session 필드로부터 phase 유도 (순수)

2.3 Classifier (regex first, LLM fallback)

  • 신규 src/skills/onboarding/state/classifier.ts:
    • 1단계: message-filter.ts에서 가져온 regex + 추가 패턴으로 IntentCandidate[] 생성
    • 1단계 unknown 또는 confidence < threshold → 2단계 LLM (CLASSIFIER_FALLBACK_MODEL, response_format: {type: "json_object"}, max_tokens=16, schema {"intent": "..."})
  • 신규 src/skills/onboarding/state/intent-keywords.ts: intent → 기대 키워드 사전 (validator에서 사용)
    export const EXPECTED_KEYWORDS: Record<Intent["kind"], string[]> = {
      "status-question": ["남았", "완료", "아직", "끝났"],
      "discord-question": ["디스코드"],
      ...
    };
    

2.4 Skill 진입점 재작성

  • src/skills/onboarding/skill.ts의 handle() 재작성 (PR 2a에서 onboarding-skill.ts를 git mv로 개명 — §5.4):
    // src/skills/onboarding/skill.ts (PR 2a git mv로 개명된 파일)
    async handle(req, history) {
      const session = await this.loadSession(req);
      const intent = await classifier.classify(req.userMessage, req.trigger);
      const derived = derive(session, req.trigger, intent);
      if (!derived.shouldRespond) return makeEmpty(req.requestId);
      if (derived.responseMode === "template") return this.handleTemplate(req, derived, session);
      // Phase 4/5에서 orchestrator로 위임. 지금은 기존 generateLlmText 호출하되 derived 사용.
      return this.handleLlm(req, derived, session, history);
    }
    
  • message-filter.ts, onboarding-prompts.ts는 PR 2a에서는 유지(@deprecated 표시만). classifier가 내부적으로 message-filter 함수 재사용. golden set 확보 후 PR 2b에서 message-filter.ts 삭제, Phase 3 PR에서 onboarding-prompts.ts 삭제. (개명은 line 위 코드 블록 주석 참조 — git mv + handle 재작성을 한 커밋으로)

2.5 eval:capture helper (Phase 5용 준비)

  • 신규 src/eval/capture.ts (스켈레톤 먼저):
    • MongoDB events에서 category: "message.received" 샘플링
    • { input: { request, session, roomContext }, expected: { ...skeleton } } JSONL 출력
    • expected는 빈 필드로 생성 → 사용자가 수동 큐레이션
  • 신규 src/eval/anonymize.ts (capture 파이프라인의 강제 단계):
    • 닉네임/userId: 결정적 해시(SHA256(salt+value).slice(0,8)) 후 user_<hash> / 닉네임은 <nick:hash>로 치환. salt는 소스 하드코딩 상수(EVAL_ANON_SALT, env 아님 — 익명화 강도가 아니라 일관성 목적)
    • EVAL_ANON_SALT 저장 위치: src/eval/anonymize.ts 상단에 const EVAL_ANON_SALT = "lolympus-agent-v1" as const; 로 하드코딩. env-vars/Infisical 경유 X — 값이 바뀌면 기존 golden set과 해시 불일치해서 의미 없음. 값 변경은 golden set 재캡처와 동시에만 허용(PR 설명에 명시)
    • chatroomId: 동일 방식으로 room_<hash>
    • 메시지 본문: 전화번호(/01[016789][- ]?\d{3,4}[- ]?\d{4}/), 이메일, 카드번호 패턴, KakaoTalk 오픈채팅 링크(open.kakao.com/o/... 토큰), Discord 초대(discord.gg/...)을 [REDACTED:phone] 등으로 치환
    • 기타 ID 필드(deviceId, sessionToken 등)는 화이트리스트 외 전부 제거
    • 타임스탬프: 절대시각 → 상대(+0s, +12s 등)로 변환해 시점 추적 어렵게
    • capture는 위 파이프라인을 항상 통과시킴 (--no-anonymize 플래그 미제공). golden set 커밋 시 평문 PII가 들어갈 수 없도록 강제
  • src/eval/cli.ts에 eval:capture 명령 추가

2.6 테스트

  • src/skills/onboarding/state/derive.test.ts — 5–10개 불변식 (shouldRespond=false면 tier=0 & responseMode=skip, completed phase면 responseMode=template or skip 등)
  • src/skills/onboarding/state/classifier.test.ts — 기존 message-filter 회귀 케이스 복붙해서 동일 출력 검증

검증

  • 수동: 로컬에서 기존 요청 5–10종을 NATS로 쏴서 v1 시절과 유사한 응답 나오는지 확인
  • Phase 2 끝난 후 npm run eval:capture로 golden set 30–50건 추출 → 사용자 수동 큐레이션 (이 작업은 사용자 몫)

Phase 3 — Context Engineering + Blackboard (4–5일)

목표: 응답 품질 ↑, prompt 토큰 ~50% 감축.

작업

3.1 5-layer prompt

  • 신규 src/skills/onboarding/prompts/layers.ts:
    • personaLayer(): 역할 정의, 변하지 않음 (~200 tok)
    • policyLayer(intent, opts: { toolPolicy?: string }): 답변 원칙만. intent별 조항 선별 (~100 tok). toolPolicy는 optional — Phase 3 시점엔 주입하지 않음. Phase 4에서 toolPolicy 인자로 tool-policy.ts 출력을 넘겨받아 layer 하단에 append
    • stateLayer(session): 닉네임/하트 상태 (~50 tok). deadline은 UTC 기반, 프롬프트에는 KST로 변환해 표시
    • examplesLayer(intent, n=3): intent 매칭 예시 n개
    • contextLayer(roomContext, history, blackboard, summary): 요약 (~300 tok)
  • Tool 사용 정책은 Phase 4에서 신설 (§9.4.3). Phase 3 policyLayer에는 tool 관련 문구를 넣지 않아 dead text 방지.

Conversation history slice 책임 (§3.1.1):

  • conversation-store는 FIFO 20개 원본 유지(변경 없음). builder.ts 책임: summary 존재 시 history.slice(-5)로 잘라 프롬프트에 주입, 없으면 전체(최대 20). store는 얇게 유지.
  • 신규 src/skills/onboarding/prompts/examples.ts:
    • 기존 prompt의 15개 예시를 intent별로 분류해 Record<Intent["kind"], Example[]>
  • 신규 src/skills/onboarding/prompts/builder.ts:
    export class PromptBuilder {
      static forDerived(d: DerivedState, ctx: PromptContext) { ... }
      build(): ChatMessage[] { return [
        { role: "system", content: [persona, policy, state, examples, context].join("\n\n") },
        ...historyAsMessages,
        { role: "user", content: userMessage },
      ]; }
    }
    
  • persona+policy를 항상 맨 앞에 (SGLang/vLLM RadixAttention prefix cache 활용. CLIPROXY는 OpenAI compat이라 명시적 cache_control 마킹은 미지원 — provider abstraction에 capabilities.promptCache=false 고정. 향후 Anthropic 직접 endpoint 추가 시 layer 마킹 hook만 활용)
  • onboarding-prompts.ts는 이 PR에서 삭제

contextLayer 슬롯 상세 (상기 5-layer 중 가장 가변적이므로 별도 명시):

[최근 요약]
{summary ?? "(요약 없음)"}

[최근 대화 (최신 5턴)]
{history.slice(-5)}

[방 분위기]
{roomContext.summary}

[메모]
- lastIntent: {bb.lastIntent}
- openQuestions: {bb.openQuestions.join(", ")}

summary가 있으면 history는 최신 5턴으로 절단(token 절감). 없으면 전체 history(최대 20개) 사용. slice 책임은 상기 "Conversation history slice 책임"과 동일 (builder).

3.2 Blackboard

  • 신규 src/skills/onboarding/state/blackboard.ts:
    interface Blackboard {
      lastIntent?: Intent["kind"];
      lastIntentAt?: string; // UTC ISO
      openQuestions: string[];
      flaggedIssues: string[];
      recentNicknameAttempts: string[];
      toneMemory: { greetedAt?: string; thankedAt?: string };
    }
    
  • Redis lolympus-agent:bb:{chatroomId}:{userId}, TTL BLACKBOARD_TTL_SEC
  • load(), update(patch), save()
  • OnboardingSkill.handle 흐름:
    1. bb = await blackboard.load()
    2. builder.build({ ..., blackboard: bb })
    3. 응답 생성 후 blackboard.update({ lastIntent: derived.intent.kind, lastIntentAt: nowUtc() }) + save

3.3 Conversation summary (비동기 트리거)

  • 수정 src/conversation/conversation-store.ts:
    • appendMessage 후 history.length > 5 이면 Redis Stream lolympus-agent:background에 XADD * type summarize chatroomId ... userId ... 발행
    • summary slot: Redis String lolympus-agent:summary:{chatroomId}:{userId}, TTL CONVERSATION_SUMMARY_TTL_SEC
  • 신규 src/conversation/summarizer.ts:
    • summarize(history, existingSummary?): Promise<string> — CLIPROXY gpt-5.3-codex-spark 호출, max_tokens=256
  • 이 summarizer는 Phase 5의 worker가 consume. Phase 3에서는 publish만 구현 (worker는 stub).

3.4 테스트/smoke

  • prompts/builder.test.ts — 토큰 수 측정(단순 길이 기준), intent별 다른 예시 선택되는지
  • Phase 3 완료 후 npm run eval로 Phase 2 시점 대비 regression 확인 (golden set 기준)

검증

  • 기존 prompt 토큰(약 1800) → 새 prompt 토큰(약 900) 감소 확인 (OTel span attribute gen_ai.usage.input_tokens)
  • 수동: 5개 대표 시나리오에서 응답 톤/품질 동등 이상 확인

Phase 4 — Tool Calling + Validation (5–7일)

목표: 환각 제거. deterministic 검증을 LLM이 호출하도록.

작업

4.1 Tool 인프라

  • 신규 src/tools/tool.ts:
    export interface Tool<A, R> {
      name: string;
      description: string;           // Anthropic 연구상 가장 중요한 prompt slot
      argsSchema: z.ZodType<A>;
      resultSchema: z.ZodType<R>;
      execute(args: A, ctx: ToolContext): Promise<R>;
    }
    
  • 신규 src/tools/registry.ts: register(tool), get(name), list()
  • 신규 src/tools/parser.ts: Hermes <tool_call>{...}</tool_call> + OpenAI tool_calls 양쪽 파싱, 정규화된 ToolCall[] 반환
  • 신규 src/tools/serializer.ts: tool 선언을 system prompt에 주입하는 포맷터. Hermes spec 준수(<tools>...</tools>), OpenAI tools 배열도 생성 (provider별 선택)

4.2 빌트인 도구

  • src/tools/builtins/validate-nickname.ts:
    • args: { nickname: string }, result: { valid: boolean, issues: NicknameIssue[], normalized?: string }
    • analyzeNicknameIssues 래핑
  • src/tools/builtins/check-onboarding-progress.ts:
    • args: { chatroomId, userId }, result: { nicknameDone, photoDone, remainingSteps, deadlineInHours }
    • session 읽어 가공
  • src/tools/builtins/lookup-community-rule.ts:
    • args: { topic: "age" | "tier-codes" | "discord-link" | "heart-rule" | "nickname-format" | "deadline" }, result: { topic, text, source: "constants" }
    • SoT: 신규 src/skills/onboarding/constants.ts 한 곳에서 모든 규칙 상수 export. 내용:
      • VALID_TIERS = ["GM","I","B","S","G","P","E","D","M","C","U"]
      • MIN_AGE, MAX_AGE (현재 27+ 정책)
      • DISCORD_INVITE_URL
      • HEART_RULE_TEXT, NICKNAME_FORMAT_TEXT
      • DEADLINE_NEAR_THRESHOLD_MIN — 데드라인까지 남은 시간이 이 값(분) 이하이면 phase=deadline-near로 유도 (derive.ts / transitions.ts가 참조)
      • ESCALATION_BUDGET_PER_TURN — §9.4.6 escalation 상한
    • SoT 정책: env를 단일 소스로. constants.ts는 env 로드 wrapper만 제공:
      export const DEADLINE_NEAR_THRESHOLD_MIN = Number(process.env.DEADLINE_NEAR_THRESHOLD_MIN ?? 30);
      export const ESCALATION_BUDGET_PER_TURN = Number(process.env.ESCALATION_BUDGET_PER_TURN ?? 2);
      // 문자열/JSON 상수(VALID_TIERS, HEART_RULE_TEXT 등)는 env 없이 constants.ts에 직접 기재 (유일 SoT)
      
      기본값은 env catalog(§6.2) 기준. constants.ts는 값을 독자 하드코딩하지 않음(중복 SoT 금지).
    • validate-nickname / 템플릿 fallback / lookup-community-rule이 모두 이 파일을 참조 (중복 정의 금지)
    • tool은 단순히 CONSTANTS[topic] 조회 후 zod로 narrowing
  • src/tools/builtins/get-room-context.ts:
    • args: { chatroomId, limit?: number }, result: { messages: RoomMessage[] }
    • RoomContextService 래핑
    • 주의: LLM이 호출한 경우만 조회. Phase 4 이전에는 OnboardingSkill.handleUserMessage에서 unconditional 조회 → 이걸 LLM 결정 기반으로 전환(contextLayer에는 blackboard 요약만 포함하고, 상세 room 조회는 LLM이 필요하다 판단할 때만 tool 호출)

4.3 Tool 사용 정책 (prompt 주입)

  • 신규 src/skills/onboarding/prompts/tool-policy.ts:
    export function buildToolPolicy(intent: Intent["kind"], phase: OnboardingPhase["kind"]): string {
      // intent/phase 조합 → "언제 어떤 tool을 부를지" 짧은 지침 생성
      // 예: nickname-rejected + nickname-pending → "닉네임 후보가 나오면 validate-nickname을 먼저 호출한 뒤 diff를 설명"
      // answer-direct 계열 → "도구 호출 없이 즉답"
    }
    
  • prompts/builder.ts가 policy layer 구성 시 buildToolPolicy(derived.intent.kind, derived.phase.kind)를 호출해 system prompt에 주입
  • 용도:
    • LLM이 tool을 과도하게 호출/미호출하지 않도록 intent별 기대 동작 명시
    • Planner(§9.5.1)가 suggestedTools를 고를 때도 동일 정책을 참고 (prompt에 함께 주입)
    • serializer.ts가 선언하는 tool 자체는 전체(혹은 Planner subset) — 이 정책은 사용 가이드라는 점에서 구분
  • intent/phase 조합 수가 적고(~10×9=90) 순수 함수라 간단한 lookup table + default로 구현. 별도 LLM 호출 없음

4.4 Tool loop

  • 신규 src/skills/onboarding/runtime/tool-loop.ts:
    async runWithTools(messages, toolSet, llmOpts, maxHops=2): Promise<string> {
      for (let hop = 0; hop <= maxHops; hop++) {
        const resp = await llm.chatCompletion(messages, llmOpts);
        const toolCalls = parseToolCalls(resp);
        if (toolCalls.length === 0) return resp.content;
        if (hop === maxHops) {
          // hop 초과: "이제 tool 없이 답만 해" 강제 프롬프트로 한번 더 호출
          messages.push({ role: "user", content: "도구 없이 지금까지 얻은 정보로만 한국어 문장으로 답해줘." });
          const finalResp = await llm.chatCompletion(messages, { ...llmOpts, tools: undefined, maxTokens: Math.min(256, llmOpts.maxTokens) });
          return finalResp.content;
        }
        for (const call of toolCalls) {
          const tool = registry.get(call.name);
          const validated = tool.argsSchema.parse(call.arguments);
          const result = await withToolSpan(call.name, validated, () => tool.execute(validated, toolCtx));
          messages.push(provider.formatToolResult(call, result));  // §5.2 provider 추상화 경유 — cliproxy/openrouter는 role:"tool", llama는 Hermes <tool_response>
        }
      }
    }
    
  • 실패 시 (parse 에러, tool throw) → 템플릿 fallback

4.5 Validator

  • 신규 src/skills/onboarding/runtime/validator.ts:
    • 기존 postProcessResponse 흡수 (URL 화이트리스트, 마크다운 제거, 600자 절단, <think> 제거, [NO_RESPONSE] 처리)
    • 신규 규칙:
      • stateConsistency: 응답에 "디스코드" + phase가 nickname/photo pending → reject
      • nicknameExampleConsistency: 응답에 닉네임 예시(.+/\d{2}/(남|여)/[GIBSPEDMCU]|GM)가 있으면 regex 통과
      • intentAlignment: EXPECTED_KEYWORDS[intent] 중 하나 이상 포함
      • minLength: !allowShortResponse && length < 10 → reject
      • phraseRepetition: bigram 3회+ 반복 → soft-warn
    • 반환: { status: "pass" | "soft-warn" | "reject", text: string, reasons: string[] }
    • reject → 템플릿 fallback

4.6 Self-critique (Tier 2 한정) + Dynamic Tier Escalation

  • 신규 src/skills/onboarding/runtime/critic.ts:
    • critique(draft, derived, ctx): Promise<{ text: string; changed: boolean }>
    • Critic prompt: "교정 필요하면 교정된 응답만, 필요 없으면 [OK]만"
    • max_tokens=512 cap. [OK]로 시작 → changed=false (원본 유지)
  • Dynamic tier escalation (orchestrator가 validator 결과 기반으로 동적 승격):
    • derived.tier는 시작 tier일 뿐. validator/critic 결과에 따라 같은 turn 내에서 승격 가능
    • 승격 규칙:
      • tier 0 응답이 validator soft-warn ≥ 2 → tier 1 Planner+Responder로 1회 재시도
      • tier 1 응답이 validator soft-warn ≥ 2 또는 intentAlignment 실패 → tier 2 Critic 호출
      • tier 2 응답도 validator reject → 템플릿 fallback (이미 §9.4.5 정책)
    • escalation budget: turn당 추가 LLM 호출 ≤ 2회. deadline 50% 이상 잔여 + budget 남았을 때만 escalate. 그 외엔 현재 응답 그대로 통과 (validator soft-warn은 로그만)
    • 승격 사실은 OTel span attribute agent.tier.escalated_from/to에 기록 → shadow eval에서 분포 확인
  • Phase 4 / Phase 5 경계: §9.4.6의 escalation 규칙/예산 정의는 Phase 4 PR에 포함하되, 실제 실행 orchestrator는 §9.5.1에서 완성. Phase 4 PR이 보장하는 건 (a) validator가 status: "pass" | "soft-warn" | "reject" + warnings[] 을 반환하는 인터페이스, (b) critic이 [OK] 규약을 지키는 인터페이스 두 가지. Phase 4 orchestrator는 §9.4.7 "얇게" — llm / llm-with-tools 분기만. escalation loop/budget/deadline 체크는 §9.5.1 orchestrator가 소비.

4.7 Orchestrator 통합 (얇게, Phase 5에서 확장)

  • skill.ts의 LLM 경로(Phase 2에서 개명 완료)에서 derived.responseMode === "llm-with-tools" 시 tool-loop.runWithTools 호출, 그 외는 단순 chatCompletion

4.8 테스트

  • validator.test.ts: 10개 케이스 (state 모순, 닉네임 예시 regex, intent 매칭 등)
  • tools/parser.test.ts: Hermes + OpenAI 포맷 각각 3-5개
  • tool-loop.test.ts: mock LLM으로 hop 동작 시나리오

검증

  • npm run eval regression 없음
  • 수동: nickname-rejected 3종(3-part, 나이 문자, 티어 오탈자) → validate-nickname 호출 트레이스 + 정확한 diff 응답

Phase 5 — Orchestration + Eval + Alerting (5–7일)

목표: 지속 개선 루프 + tier별 모델 라우팅 + 실시간 품질 모니터링.

작업

5.1 Orchestrator

  • 신규 src/skills/onboarding/runtime/orchestrator.ts:
    async run(derived, messages, ctx): Promise<string> {
      const deadline = ctx.deadlineAt; // §7 참조 — 본체 NATS timeout 5s에서 안전 마진 0.5s 차감
      switch (derived.tier) {
        case 0: return this.runTier0(derived, messages, ctx, deadline);
        case 1: return this.runTier1(derived, messages, ctx, deadline);
        case 2: return this.runTier2(derived, messages, ctx, deadline);
      }
    }
    // tier 0: 단일 chatCompletion (+tool loop if llm-with-tools)
    // tier 1: Planner LLM (PlannerOutput JSON) → Responder LLM
    // tier 2: tier 1 + Critic → (조건부 Rewrite)
    
  • skill.ts(Phase 2에서 개명)에서 이 orchestrator 사용

5.1.1 Planner output 스키마 (zod)

  • 신규 src/skills/onboarding/runtime/planner-schema.ts:
    import { z } from "zod";
    
    export const PlannerOutputSchema = z.object({
      approach: z.enum([
        "answer-direct", "ask-clarification", "redirect-to-step",
        "validate-then-explain", "lookup-rule-then-answer", "soft-decline",
      ]),
      targetPhase: z.enum([
        "fresh", "nickname-pending", "photo-pending", "both-pending",
        "nickname-rejected", "photo-rejected", "deadline-near", "completed", "timed-out",
      ]).optional(),
      mustInclude: z.array(z.string().min(1).max(80)).max(5).default([]),
      mustAvoid:   z.array(z.string().min(1).max(80)).max(5).default([]),
      suggestedTools: z.array(z.enum([
        "validate-nickname", "check-onboarding-progress",
        "lookup-community-rule", "get-room-context",
      ])).max(3).default([]),
      tone: z.enum(["friendly", "concise", "encouraging", "neutral", "apologetic"]).default("friendly"),
      targetLengthChars: z.number().int().min(20).max(500).default(150),
      rationale: z.string().max(200), // 디버깅/eval용. 응답 본문에는 노출 X
    });
    export type PlannerOutput = z.infer<typeof PlannerOutputSchema>;
    
  • Planner 호출 옵션: response_format: { type: "json_object" }, max_tokens: PLANNER_MAX_TOKENS, TIER1_PLANNER_MODEL.
  • 파싱 실패 fallback: zod parse 실패 시 1회 재시도("스키마에 맞춰 다시"), 그래도 실패하면 Planner 결과 무시 → Responder를 derived 기반 기본값으로 직접 호출 (tier 0 경로와 동일하게 degrade).
  • Responder는 system prompt에 PlannerOutput을 "[PLAN] approach=X, mustInclude=[...]" 형태로 주입. mustInclude/mustAvoid는 §9.4.5 validator가 동일 케이스에서 재검증.
  • suggestedTools 전달 방식 (Planner → tool-loop 연계):
    • Responder 호출 시 prompt 주입뿐 아니라 tool-loop에 toolSet 제한 전달:
      const toolSet = plan.suggestedTools.length > 0
        ? registry.pick(plan.suggestedTools)   // 화이트리스트
        : registry.all();                       // Planner가 비워두면 전체 허용
      return runWithTools(messages, toolSet, { ...llmOpts, tier: 1 });
      
    • 이렇게 하면 serializer가 실제 선언하는 tool도 그 subset으로 제한 → LLM이 관계 없는 tool 호출 확률 ↓, 토큰 절감.
    • Planner가 approach="answer-direct"이면 toolSet=[] 강제 → tool-loop가 hop 0에서 종료.

5.2 LLM client tier routing

  • 수정 src/llm/llm-client.ts: chatCompletion(messages, opts) — routing.ts로 위임. opts 타입:
    interface ChatCompletionOpts {
      tier: 0 | 1 | 2;
      modelOverride?: string;
      tools?: Tool<any, any>[];              // Phase 4 tool-loop가 주입
      jsonMode?: boolean;                     // response_format: json_object
      maxTokens?: number;                     // 미지정 시 tier별 기본(TIER{N}_MAX_TOKENS)
      temperature?: number;
      signal?: AbortSignal;                   // §7 deadline 전파 — 초과 시 AbortError → validator reject → 템플릿 fallback
      deadlineMs?: number;                    // 남은 budget 힌트. provider가 내부 http 타임아웃에 반영
      role?: "planner" | "responder" | "critic"; // routing.selectModel용
    }
    
  • 신규 src/llm/routing.ts:
    function selectProviders(tier): Provider[] {
      const chain = [cliproxy];
      if (OPENROUTER_ENABLED) chain.push(openrouter);
      chain.push(llama);
      return chain;
    }
    function selectModel(tier, role?): string {
      if (role === "planner") return TIER1_PLANNER_MODEL;
      if (role === "critic") return TIER2_CRITIC_MODEL;
      return tier === 0 ? TIER0_MODEL : TIER1_RESPONDER_MODEL;
    }
    
  • 신규 src/llm/providers/{cliproxy,llama,openrouter}.ts: 공통 인터페이스
    export interface Provider {
      name: "cliproxy" | "llama" | "openrouter";
      capabilities: {
        jsonMode: boolean;          // response_format: json_object 지원
        toolCalls: "openai" | "hermes" | "none"; // 네이티브 tool 포맷
        promptCache: false;          // 현재 모든 provider false (CLIPROXY OpenAI compat은 자동 prefix cache만)
      };
      complete(req: NormalizedRequest): Promise<NormalizedResponse>;
      formatToolDeclarations(tools: Tool[]): { systemAddendum?: string; openAiTools?: any[] };
      formatToolResult(call: ToolCall, result: unknown): ChatMessage;
    }
    
  • provider별 tool result 직렬화 (Phase 4 §9.4.4 tool-loop이 이걸 호출):
    • cliproxy.formatToolResult → { role: "tool", tool_call_id: call.id, content: JSON.stringify(result) }
    • openrouter.formatToolResult → 동일 (OpenAI 호환)
    • llama.formatToolResult → { role: "user", content: "<tool_response>\n" + JSON.stringify({name: call.name, result}) + "\n</tool_response>" } (Hermes 규약)
  • provider별 tool 선언 주입:
    • cliproxy/openrouter → request tools 필드(OpenAI tools array)
    • llama → system prompt 끝에 <tools>[...]</tools> 블록 추가, parser는 응답에서 <tool_call>...</tool_call> 매칭
  • llama provider는 response_format 미지원 가정 → Hermes <json>...</json> 포맷으로 강제, parser가 감지

5.3 Golden set + runner + judges

  • src/eval/golden/onboarding.jsonl (사용자 큐레이션 결과 여기에 커밋. PR 첨부)
  • 신규 src/eval/runner.ts:
    • golden 로드 → 각 케이스를 in-process에서 실행 (NATS 거치지 않음, Agent.handleRequest를 직접 함수 호출)
    • rule-judge + llm-judge 각각 점수화
    • 리포트: eval-reports/{timestamp}.json + 콘솔 요약
  • 신규 src/eval/judges/rule-judge.ts:
    • expected의 mustIncludeAny, mustNotInclude, responseMode, intent 매칭
  • 신규 src/eval/judges/llm-judge.ts:
    • CLIPROXY gpt-5.3-codex-spark 호출
    • prompt: "친근함(1-5), 정확성(1-5), 간결성(1-5), 범위준수(1-5) + 한줄 이유"
    • response_format: json_object로 강제
  • 신규 src/eval/cli.ts: commander/yargs 기반 eval, eval:capture, eval:baseline (현재 baseline 업데이트)
  • package.json: "eval": "tsx src/eval/cli.ts run --set=golden", "eval:capture": "tsx src/eval/cli.ts capture"

5.4 Shadow eval + Worker

  • 신규 src/eval/shadow-bus.ts:
    • publish(input, output, derived): void — XADD lolympus-agent:background MAXLEN ~ $BACKGROUND_STREAM_MAXLEN * type shadow-eval input ... output ... derived ... fire-and-forget. MAXLEN은 env에서 로드 (리터럴 금지)
    • Stratified sampling (tier별 분리, 균등 sampling이면 tier 1/2가 거의 안 잡힘):
      const rate = {
        0: SHADOW_EVAL_SAMPLING_RATE_TIER0, // 기본 0.1
        1: SHADOW_EVAL_SAMPLING_RATE_TIER1, // 기본 0.5
        2: SHADOW_EVAL_SAMPLING_RATE_TIER2, // 기본 1.0
      }[derived.tier];
      if (Math.random() >= rate) return;
      
  • 신규 src/eval/shadow-worker.ts:
    • Redis Stream consumer group bg-worker, block 5s
    • type=shadow-eval → llm-judge 호출 → XADD lolympus-agent:eval:results MAXLEN ~ $EVAL_STREAM_MAXLEN * ... → XACK (MAXLEN 누락 시 Stream 무한 증가, TTL 미적용)
    • type=summarize → summarizer 호출 → SET lolympus-agent:summary:{chatroomId}:{userId} <text> EX $CONVERSATION_SUMMARY_TTL_SEC (TTL 필수, 기본 24h. 누락 시 summary가 영구 저장됨) → XACK
    • Retry 집계: Stream 메시지는 불변이므로 retry count를 메시지 field로 덮어쓰지 않고 consumer group의 XPENDING delivery count 사용. delivery count ≥ 3이면 DLQ로 이동 — XADD lolympus-agent:background:dlq * type <orig> payload <json> retryCount <n> lastError <msg> originalId <streamId> 후 원본은 XACK으로 종료 (사일런트 drop 방지)
    • 부트스트랩 절차 (worker 시작 시 1회):
      try { await redis.xgroup("CREATE", "lolympus-agent:background", "bg-worker", "$", "MKSTREAM"); }
      catch (e) { if (!String(e).includes("BUSYGROUP")) throw e; } // 이미 있으면 무시
      
    • Pending entries 복구 (worker 재기동 시): 시작 직후 XPENDING ... bg-worker - + 100 조회 → XCLAIM으로 본인 consumer로 이양 → 처리 → 위와 동일한 retry/DLQ 정책 적용
    • Graceful shutdown: SIGTERM/SIGINT 수신 시 (1) 신규 XREADGROUP 호출 중단, (2) in-flight 작업 완료까지 최대 10s 대기, (3) XACK 마무리 후 redis quit. PM2 kill_timeout: 12000 설정
    • DLQ 조사 절차 (수동 운영): redis-cli XRANGE lolympus-agent:background:dlq - + COUNT 50으로 payload/retryCount/lastError 확인. 재처리 자동화 헬퍼는 필요 시점에 별도 추가 (현 단계에서는 구현 X — DLQ 엔트리 발생 자체가 이상 신호이므로 사용자 수동 조사 우선). alert 별도 발송 X — 정기 점검으로 충분
  • 신규 src/workers/background.ts: 위 worker를 부트스트랩하는 엔트리 (별도 PM2). signal handler 등록 + redis/nats 연결 lifecycle 관리
  • ecosystem.config.js:
    module.exports = {
      apps: [
        { name: "agent", script: "dist/main.js", instances: 1, max_memory_restart: "512M" },
        { name: "agent-worker", script: "dist/workers/background.js", instances: 1, max_memory_restart: "512M" },
      ]
    };
    
  • launch-server.ps1: 기존 분기(PM2/직접실행) 유지하되, PM2 분기에서 pm2 start ecosystem.config.js --only agent,agent-worker로 변경. 직접 실행은 main만(worker는 PM2 강제)

5.5 Alert

  • 신규 src/observability/alert.ts:
    • sendAlert(payload: AlertPayload): Promise<void>
    • Rate limit: Redis lolympus-agent:alert:dedupe:{kind} SETNX + EXPIRE
    • NATS publish lolympus-agent.alert
  • shadow-worker가 주기적으로 (1분 tick) eval 결과 + circuit 상태 aggregate:
    • p95 latency > ALERT_THRESHOLD_P95_LATENCY_MS → alert
    • 최근 window 평균 점수가 baseline 대비 ALERT_THRESHOLD_EVAL_SCORE_DROP_PCT 하락 → alert
    • LLM error rate > ALERT_THRESHOLD_LLM_ERROR_RATE → alert
    • Circuit breaker open 감지: worker가 1분 tick마다 SCAN 0 MATCH lolympus-agent:circuit:* COUNT 100 (cursor 0 될 때까지 loop — KEYS는 blocking이라 금지) → 각 Hash의 state=="open"이면 kind=endpoint-down alert publish. rate-limit은 §8 Redis Schema의 lolympus-agent:alert:dedupe:endpoint:{endpointHash} key로 처리 (동일 endpoint 재알림 5분 내 1회). agent process 측에서 pub/sub 이벤트를 따로 내보내지 않음 — Redis Hash가 SoT이므로 worker가 폴링만으로 충분
  • lolympus 본체 측 변경: lolympus-agent.alert 구독 후 관리자 채팅방에 카톡 발송 (본체 PR 별도)

5.6 Summary worker 활성화

  • Phase 3에서 stub으로 둔 consumer를 shadow-worker에서 실제 구현
  • summary 생성 실패 시 2회 재시도, 그 후 drop + warn log

5.7 테스트

  • orchestrator.test.ts: tier 분기 mock 테스트
  • judges/*.test.ts: rule-judge 고정 case, llm-judge는 mock response
  • E2E smoke: npm run eval 돌려 골든셋 ≥ 80% pass

검증

  1. shadow eval: 프로덕션 부팅 5분 후 XLEN lolympus-agent:eval:results ≥ 1
  2. 고의로 latency 3s 초과 응답 유발 → lolympus-agent.alert publish 확인 (NATS 로그)
  3. OpenRouter enable → tier 1 호출 시 라우팅 확인
  4. npm run eval 결과가 eval-reports/에 저장, baseline과 diff 출력

10. Migration Strategy (v2 직진)

  1. Phase 0~5는 각 독립 PR로 순차 머지. 각 PR 끝에 v2가 곧바로 활성화됨.
  2. v1 코드는 각 PR 내에서 즉시 삭제 (alias 단계 없음). backward-compat 고려 없음.
    • 예외: Phase 2는 golden set 확보를 위해 §9 Phase 2의 PR 2a/2b 분할 정책 적용 — PR 2a에서 message-filter.ts는 @deprecated 표시만, PR 2b에서 npm run eval 통과 후 삭제. onboarding-prompts.ts는 Phase 3 PR에서 builder 도입과 함께 삭제. 이 지연은 feature flag/alias 없이 "삭제 시점"만 1 PR 미루는 것이라 v2 직진 원칙을 어기지 않음.
  3. feature flag 없음.
  4. Phase 2 PR 2a 머지 후 → 사용자가 npm run eval:capture 실행 → golden set 큐레이션(30–50건) → 별도 PR로 src/eval/golden/onboarding.jsonl 커밋 → 이후 PR 2b 진행.
  5. Phase 3 이후 각 PR에서 npm run eval을 CI gate로. 회귀 시 PR 블록.
  6. 프로덕션 배포 후 shadow eval 점수 하락 알림 → 사용자 판단으로 git revert (자동 rollback 없음).

11. Risks & Mitigations

리스크 영향 완화
CLIPROXY 장애 모든 tier 영향 circuit breaker + 로컬 Qwen 폴백. Phase 5의 alert가 감지
4B Qwen 폴백 품질 tier 1/2에서 fallback 시 응답 품질 ↓ CLIPROXY 실패로 llama 폴백 시 §9.5.2 provider가 capabilities.toolCalls="hermes"에 맞춰 tool 선언/결과를 Hermes 포맷으로 자동 변환. 정확성은 §9.4.5 validator + Phase 5 escalation으로 재검증/재시도하여 보완
Multi-layer prompt가 오히려 품질 하락 응답 톤 변화 Phase 3 완료 후 npm run eval smoke로 확인, 안 좋으면 layers 재조정
shadow eval 비용 CLIPROXY 호출량 tier별 sampling rate 조절 (SHADOW_EVAL_SAMPLING_RATE_TIER{0,1,2}, prod 기본 tier 0=0.1, tier 1=0.5, tier 2=1.0)
Phase 3/4 직진 후 Phase 5에서 버그 발견 디버깅 어려움 Phase 끝마다 smoke eval 돌리고, 각 phase PR 분리 유지 (revert 용이)
OTel overhead 부하 ↑ prod sampling 10%, exporter=stdout(망가지지 않음)
OpenAI-compat JSON 모드 비호환 일부 응답 파싱 실패 Hermes <json> fallback 파서. llama provider에서 강제
launch-server.ps1 Windows only 배포 환경 제약 기존 Windows 환경 그대로 유지. Linux 배포는 별도 검토
lolympus 본체 lolympus-agent.alert 구독 미구현 시 alert 사일런트 drop Phase 5 롤아웃 전 본체 변경 PR 먼저
eval:capture가 MongoDB 부하 일시적 read 부하 샘플링 + 쿼리 시 {chatroomId, category, "data.body.timestamp"} 복합 인덱스 확인/생성. eval:capture 실행은 개발자 수동

12. Verification Plan

Phase 별 (각 phase PR 머지 조건)

Phase 검증
0 typecheck && lint && build && start:dev 통과, 기능 동일
1 stdout OTel span + pino pretty, 100 req 중 health 호출 ≤ 5회
2a derive.test.ts, classifier.test.ts 통과. message-filter.ts와 classifier의 동일 입력 회귀 테스트 통과(classifier 내부 재사용이라 의미 있음). 수동 5 시나리오 회귀 없음. onboarding-skill.ts → skill.ts 개명 확인
2-curation (golden set 커밋 전용 PR) eval:capture 결과 jsonl에 평문 PII 0건(grep 기반 검사), expected 필드 30–50건 채워짐, npm run eval --dry-run이 golden set 파싱 성공
2b npm run eval 골든셋 규칙 판정 ≥ 80% pass 시 message-filter.ts 삭제 허용. 이후 grep으로 dead import 0건 확인
3 input_tokens span에서 ~50% 감소, onboarding-prompts.ts 삭제 확인, 수동 5 시나리오 품질 동등 이상, smoke npm run eval regression 없음
4 validator.test.ts, tool-loop.test.ts, tools/parser.test.ts 통과. nickname-rejected 3종에서 validate-nickname tool span 트레이스 확인. tool-policy 주입이 llm-with-tools 케이스에서만 발생 확인
5 npm run eval 골든셋 ≥ 80% pass, shadow eval 5분 내 결과 ≥ 1건, alert 재현 테스트(고의 latency 3s 초과) 통과, tier escalation 분포 로그 확인, smoke eval 실행 구간 동안 DLQ 0건(고의 부하/장애 주입 케이스는 제외)

운영 지속 검증

  • Shadow eval LLM-judge 평균 ≥ 4.0/5.0
  • p50 < 800ms, p95 < 2.8s
  • LLM error rate < 10% / 1분

13. Minor Decisions (확정 기본값)

항목 결정
영어/외국어 입력 시스템 프롬프트에 "한국어로 답변" 유지. 외국어 들어와도 한국어로 응답
MongoDB 인덱스 events 컬렉션에 {chatroomId:1, category:1, "data.body.timestamp":-1} 복합 인덱스 권장. Phase 2 eval:capture 구현 시 함께 생성 스크립트 추가 (있으면 skip)
llama.cpp JSON 모드 response_format 미지원 가정. Hermes <json>...</json> 사용 + parser.ts가 태그/순수JSON 양쪽 파싱
Skill 인터페이스 일반화 Phase 6 보류. 현재 skill 1개. 필요해지면 declareIntents() 확장
시간대 모든 코드/Redis/로그/NATS payload UTC. 카톡 사용자에게 노출되는 문장만 KST 변환
Commit 메시지 컨벤션 Conventional Commits (feat:, fix:, chore:, refactor:, test:, docs:)

14. Codex Hand-off Checklist

Codex(또는 다른 AI)가 이 plan으로 실제 코드 작업할 때 Phase 0부터 순차 진행. 각 Phase 완료 기준:

  • §9의 Phase 작업 전체 구현
  • npm run typecheck && npm run lint && npm run build && npm test 통과
  • §12의 Phase별 검증 항목 통과
  • 해당 Phase의 Critical Files 변경이 §5와 일치
  • env/키/subject 추가 시 §6/§7/§8 업데이트
  • 커밋/PR 본문에 "Phase N — <title>" 명시

참고 문서:

  • 기존 /Users/dahyeon/.claude/plans/graceful-jumping-hoare.md (초기 plan)
  • 이 문서(plan.md)가 최종 버전이며, 충돌 시 이 문서 우선

질문 대응:

  • plan에 없는 세부 결정이 나오면 이 문서의 Resolved Decisions와 최소 침습 원칙("기존 인터페이스 유지, agent.ts 최소 수정")에 부합하는 방향으로 진행.
  • 불가한 모순 발견 시 작업 중단하고 사용자에게 확인.