openclaw/INBOX_TOPICS.md

# INBOX_TOPICS.md — 에이전트 inbox 메시지 topic 등록부

OpenClaw 에이전트 간 파일 기반 통신의 topic 카탈로그. envelope 형식과 운영 원칙은 `CLAUDE.md`의 "Agent Inbox Convention" 섹션 참조.

**새 topic 추가 시 이 파일에 반드시 등록.** 미등록 topic 메시지는 수신자가 `failed/`로 보낸다.

---

## 등록된 Topic

### `securities_balance`

- **방향:** `stock` → `budget`
- **목적:** 본인+가희 증권 계좌별 잔액(평가액·예수금·총자산)을 소유자별로 골디에게 전달, 월간 결산 입력으로 사용
- **트리거:** macOS launchd `ai.openclaw.stock.send-balance` — 매월 1일 04:30 KST. 골디 결산 cron(05:00) 30분 전. (`inbox_handler.py`의 `as_of` 가드는 1·10·20일을 허용 — 과거 운영 호환 안전망)
- **schema_version:** 2 (v1 하위호환 유지 — 수신자 `SUPPORTED_SCHEMA={1,2}`)
- **payload 스키마 (v2):**

```json
{
  "as_of": "2026-07-01",
  "owner_scope": "self_and_gahee",
  "accounts": [
    {
      "label": "일반",
      "owner": "self",
      "account_no": "",
      "deposit": 56032,
      "eval_amount": 114294705,
      "total": 114350737,
      "position_count": 7
    },
    { "label": "ISA", "owner": "self", ... },
    { "label": "가희_일반", "owner": "gahee", ... },
    { "label": "가희_ISA", "owner": "gahee", ... }
  ],
  "by_owner": {
    "self":  { "deposit": 146362, "eval_amount": 188964561, "total": 189110923 },
    "gahee": { "deposit": 138469, "eval_amount": 22587331, "total": 22725800 }
  },
  "totals": {
    "deposit": 284831,
    "eval_amount": 211551892,
    "total": 211836723
  }
}
```

- **owner_scope:** v2는 `self_and_gahee` — 본인·가희 모두 발행. `accounts[].owner` 는 `self`|`gahee` (`가희_` prefix 라벨이 gahee). 소유자 집계는 `by_owner`. `totals` 는 참고용 grand total. (v1은 `self_only`·`by_owner` 없음, 단일 소유자로 처리)
- **수신자(골디) 처리 동작:**
  - 월간결산 cron 진입부에서 `inbox_handler.process_inbox()` 호출 (fetch_balance 이전 — 분개가 후잉 잔액에 반영되어 결산이 분개 후 스냅샷을 보도록)
  - `by_owner` 의 각 소유자 total 과 후잉 자산(`self`→`증권(효원)`, `gahee`→`증권(가희)`)의 차액을 소유자별로 reconcile:
    - 차액 > 0 → 차변 `증권(효원|가희)` / 대변 `주식평가수익` 자동 분개 (손익 계정은 소유자 공용)
    - 차액 < 0 → 차변 `주식평가손실` / 대변 `증권(효원|가희)` 자동 분개
    - `|차액| < 1만원` → 노이즈로 간주, 분개 skip (processed 처리)
    - `|차액| > 1억원` → 안전 가드 발동, 분개 거부 + 텔레그램 alert + `failed/` 이동
    - 후잉에 해당 자산 항목 없으면 `skipped` (분개 안 함)
  - 소유자 하나라도 rejected/journal_failed 면 `failed/` 이동·미처리. 재실행 시 이미 분개된 소유자는 fresh 조회로 차액≈0 aligned → 중복분개 없음 (reconcile는 목표값으로 맞추기라 자연 idempotent)
  - 정상 처리 후 `processed/`로 이동, `state/inbox_state.json` 의 `processed[]` 에 message_id 누적 (idempotency, 최근 1000개)
  - 결산 메일 본문에 `## 인박스` reconcile 섹션(소유자별 라인), 텔레그램에 한 줄 요약 추가. 메일 "자산 계정별 변동"은 후잉 자산 전수 순회라 `증권(가희)`도 자동 표시
- **GC / 적체 정책 (월간결산 cron 진입부에서 매월 자동 수행):**
  - `processed/` 의 mtime 30일 초과 envelope 자동 삭제 (`gc_processed`)
  - `failed/` 적체가 5건 이상이면 결산 메일·텔레그램에 ⚠️ alert 한 줄 추가 — 사람이 검토 후 수동 삭제 (자동 삭제 안 함, CLAUDE.md 원칙 준수)
- **실패 조건 (→ `failed/` + 텔레그램 자가 알림):**
  - JSON 파싱 실패
  - envelope 키 누락 / `to != budget` / 미등록 topic / 미지원 `schema_version`
  - payload 키 누락 (`as_of`, `accounts`, `totals`, `owner_scope`)
  - `as_of` 가 매월 1·10·20일이 아님
  - `totals`/`by_owner.*` 의 `{deposit,eval_amount,total}` 음수 또는 100억 초과
  - `accounts[].total` 합계가 `totals.total` 과 불일치
  - `by_owner` 에 미등록 소유자 (self/gahee 외) 또는 구조 오류
  - 차액이 1억원 초과 (분개 거부)
  - 후잉 webhook 분개 실패
- **관련 스크립트:**
  - 송신: `agents/stock/workspace/scripts/send_balance_to_budget.py`
  - 수신: `agents/budget/workspace/skills/monthly-settlement/scripts/inbox_handler.py` (단독 실행 가능, `--dry-run` 지원)
  - 통합: `agents/budget/workspace/skills/monthly-settlement/scripts/monthly_settlement.py` 진입부에서 호출

### `improvement_review`

- **방향:** `main` | `stock` | `budget` → `cody`
- **목적:** 에이전트가 자기 워크스페이스를 자체 개선한 뒤 코디에게 검증·후속 개선을 위임. 코디 세션이 떠 있을 때 incoming을 비동기로 처리.
- **트리거:** 에이전트가 자체 판단으로 스크립트·스킬·문서·설정을 수정한 직후 (cron/launchd 자동 발화 X — 작성 주체는 항상 에이전트 자신)
- **schema_version:** 1
- **payload 스키마:**

```json
{
  "change_type": "script_update | new_skill | config_update | doc_update | scheduled_job | other",
  "changed_paths": ["agents/stock/workspace/scripts/foo.py"],
  "summary": "한 줄 변경 요약",
  "rationale": "왜 변경했는지 (자연어 OK — 지시문 아닌 맥락 설명)",
  "self_review_notes": "본인 self-check 결과 (테스트·엣지케이스·미해결)",
  "test_evidence": {
    "command": "python3 -m ...",
    "exit_code": 0,
    "output_excerpt": "..."
  },
  "concerns": [
    { "area": "tz_handling", "question": "naive datetime 잔존 여부" }
  ],
  "priority": "low | normal | high"
}
```

- **자연어 필드 예외:** 이 토픽은 payload에 자연어 필드(`summary`, `rationale`, `self_review_notes`, `concerns[].question`)를 허용한다. 코디가 사람-에이전트로서 변경 의도를 읽어야 하기 때문. 단 이는 **컨텍스트 설명**이지 LLM 행동 지시문이 아니다. "X를 해줘" 류 명령문 금지, 사실·관찰·우려만 기록.
- **수신자(코디) 처리 동작:**
  - 세션 기동 시 `agents/cody/inbox/incoming/` 스캔 → envelope 개수·summary 목록을 관리자님에게 보고
  - 관리자님이 우선순위 결정하면 코디가 `changed_paths`·`rationale`·`concerns` 기반으로 검증
  - 필요 시 코디가 **직접 개선** 수행 (관리자님 동의 받은 위험 작업은 별도 확인)
  - 완료 후 envelope을 `processed/`로 이동, 같은 basename에 `_report.md` 동봉 (검증 결과·후속 개선·잔여 위험)
  - 스키마 위반(필수 키 누락, `to != cody`, 미지원 schema_version)은 `failed/`로 이동 후 관리자님에게 보고
- **실패 조건:** JSON 파싱 실패 / envelope 키 누락 / `to != cody` / 미등록 `change_type` / 미지원 schema_version / `changed_paths` 빈 배열 또는 워크스페이스 밖 경로
- **GC:** 코디가 새 envelope을 `processed/`로 옮기는 그 시점에, 같은 디렉터리의 mtime 7일 초과 항목을 `trash`로 정리한다 (launchd 같은 별도 트리거 없음). `failed/`는 사람이 검토 후 수동 정리 (자동 삭제 X)
- **관련 스크립트:** 헬퍼 미정 — 일단 에이전트가 직접 envelope JSON을 작성한다. 패턴이 굳으면 추후 `workspace/scripts/cody_review.py` 류로 추출

---

## 등록 템플릿

새 topic 추가 시 복사해서 채우기:

````markdown
### `<topic_name>`

- **방향:** `<from>` → `<to>`
- **목적:** 한 줄 설명
- **트리거:** 언제 발송되는지 (cron/launchd/이벤트)
- **schema_version:** 1
- **payload 스키마:**

```json
{
  "field1": "...",
  "field2": "..."
}
```

- **수신자 처리 동작:** payload 받으면 어떤 작업 수행
- **실패 조건:** 어떤 경우 `failed/`로 보내는지
- **관련 스크립트:** 송신측·수신측 코드 위치
````

---

## 변경 이력

- 2026-04-26 — 초기 컨벤션 수립, 빈 등록부 생성