Initial implementation of Telegram AI customer support bot

Cloudflare Workers + Hono + D1 + KV + R2 stack with 4 specialized AI agents
(onboarding, troubleshoot, asset, billing), OpenAI function calling with
7 tool definitions, human escalation, pending action approval workflow,
feedback collection, audit logging, i18n (ko/en), and Workers AI fallback.

43 source files, 45 tests passing.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,93 @@
+# CLAUDE.md - telegram-ai-support
+
+Telegram AI 고객 지원 봇. Cloudflare Workers + Hono + D1 + KV + R2 + Workers AI.
+
+## Commands
+
+```bash
+npm run typecheck     # TypeScript 타입 체크
+npm test              # Vitest 테스트 실행
+npx wrangler deploy   # Workers 배포
+npx wrangler d1 execute telegram-ai-support-db --file=schema.sql  # D1 스키마 적용
+```
+
+## Architecture
+
+```
+src/
+├── index.ts                    # Hono 앱 + cron scheduled handler
+├── types.ts                    # 모든 타입 정의 (Env, Telegram, OpenAI, DB 모델)
+├── telegram.ts                 # Telegram Bot API 래퍼
+├── security.ts                 # webhook 인증, rate limit, admin 체크
+├── agents/                     # AI 에이전트 시스템
+│   ├── base-agent.ts           # 추상 기반 (세션, AI 호출 루프, 마커 처리)
+│   ├── agent-registry.ts       # 우선순위 기반 에이전트 라우팅
+│   ├── onboarding-agent.ts     # 신규 고객 안내 (multi-round)
+│   ├── troubleshoot-agent.ts   # 장애/문제 해결 (multi-round, 에스컬레이션)
+│   ├── asset-agent.ts          # 자산 조회 (single-shot)
+│   └── billing-agent.ts        # 결제/충전 (single-shot, optimistic lock)
+├── tools/                      # OpenAI Function Calling 도구
+│   ├── index.ts                # Zod 검증 + 도구 레지스트리 + 동적 선택
+│   ├── domain-tool.ts          # 도메인 WHOIS/등록/관리
+│   ├── wallet-tool.ts          # 지갑/충전/거래내역
+│   ├── server-tool.ts          # 서버 관리 (시작/중지/재부팅)
+│   ├── service-tool.ts         # DDoS/VPN 서비스 상태
+│   ├── d2-tool.ts              # D2 다이어그램 렌더링 (Incus jp1 + R2 캐시)
+│   ├── admin-tool.ts           # 관리자 기능 (차단, 입금 확인 등)
+│   └── knowledge-tool.ts       # 지식베이스 검색
+├── services/                   # 비즈니스 로직 서비스
+│   ├── audit.ts                # 감사 로그
+│   ├── feedback.ts             # 피드백 수집/통계
+│   ├── human-handoff.ts        # 관리자 에스컬레이션
+│   ├── notification.ts         # 관리자 알림
+│   ├── pending-actions.ts      # 인프라 변경 승인 워크플로우
+│   ├── kv-cache.ts             # KV 캐시 추상화
+│   └── cron-jobs.ts            # 크론 작업 (만료 알림, 아카이빙, 모니터링)
+├── routes/                     # HTTP 라우팅
+│   ├── webhook.ts              # Telegram webhook (인증 미들웨어)
+│   ├── api.ts                  # 관리자 API
+│   ├── health.ts               # 헬스 체크
+│   └── handlers/
+│       ├── message-handler.ts  # 메시지 처리 파이프라인
+│       └── callback-handler.ts # 인라인 키보드 콜백
+├── constants/agent-config.ts   # 에이전트별 설정 (TTL, 토큰, 온도)
+├── i18n/                       # 다국어 (ko, en)
+└── utils/                      # 유틸리티
+    ├── logger.ts               # 구조화 JSON 로깅 + PII 마스킹
+    ├── patterns.ts             # 의도 감지 정규식 패턴
+    ├── session-manager.ts      # 제네릭 D1 세션 CRUD + TTL
+    ├── circuit-breaker.ts      # 서킷 브레이커 패턴
+    ├── retry.ts                # 지수 백오프 재시도
+    ├── optimistic-lock.ts      # 낙관적 잠금 (금융 데이터)
+    ├── metrics.ts              # 메트릭 수집기
+    ├── env-validation.ts       # Zod 환경 변수 검증
+    └── api-urls.ts             # OpenAI/D2 API URL 헬퍼
+```
+
+## Key Patterns
+
+- **BaseAgent**: multi-round (도구 실행 -> AI 재호출) vs single-shot (도구 호출 반환 -> 외부 실행)
+- **Agent Registry**: 우선순위 순 활성 세션 확인. `__PASSTHROUGH__` → 다음 에이전트로 이관
+- **Session markers**: `__SESSION_END__`, `[세션 종료]`, `__ESCALATE__`, `__PASSTHROUGH__`
+- **Tool selection**: 메시지 패턴 → 카테고리 → 필요한 도구만 OpenAI에 전달 (토큰 절약)
+- **Pending actions**: 위험한 인프라 변경은 `pending_actions` 테이블에 저장 → 사용자/관리자 승인 후 실행
+- **AI fallback**: OpenAI 실패 시 Workers AI (llama-3.1-8b-instruct-fp8)
+
+## Bindings (wrangler.toml)
+
+- `DB`: D1 데이터베이스
+- `AI`: Workers AI
+- `RATE_LIMIT_KV`, `SESSION_KV`, `CACHE_KV`: KV 네임스페이스
+- `ASSETS_BUCKET`: R2 버킷
+- `BOT_TOKEN`, `WEBHOOK_SECRET`, `OPENAI_API_KEY`: 시크릿
+- `ADMIN_TELEGRAM_IDS`: 쉼표 구분 관리자 ID
+- `CLOUD_ORCHESTRATOR`: 서비스 바인딩
+
+## Testing
+
+Vitest + Miniflare. 테스트 setup에서 D1 스키마 자동 초기화.
+
+```bash
+npm test                          # 전체 실행
+npx vitest run tests/security.test.ts  # 단일 파일
+```