API로 감쌀 것과 gateway에 남길 것 — OkayJing Local의 상태 변경 경계

Local app을 만들다 보면 모든 동작을 API로 만들고 싶어진다. /api/messages/send, /api/worker/talk, /api/approve 같은 endpoint를 만들면 UI에서는 편하다. 문제는 그 순간 Hermes gateway가 이미 갖고 있는 대화 의미를 우회할 수 있다는 점이다.

API는 원천 리소스의 동시성과 상태 변경을 맡는 것이 맞다. SQLite DB, Markdown, ticket, work-ledger, artifact, profile metadata, git/file/checkpoint index 같은 것들이다. 여기는 idempotency, locking, audit log, auth, readback이 필요하다.

이런 리소스는 여러 화면과 worker가 동시에 볼 수 있다. 그래서 명시적인 mutation contract가 있어야 한다. 누가 무엇을 바꿨고, 실패하면 어떻게 되돌릴 수 있는지 남아야 한다.

반대로 chat, voice, STT/TTS, media attachment, session/thread binding, approval/clarify/permission prompt lifecycle은 gateway 의미를 따라야 한다. conversation은 단순 POST가 아니다. 누가 말했고, 어느 session에 묶이고, 어떤 platform delivery로 나가며, 어떤 승인 흐름을 갖는지가 같이 붙는다.

서식지 UI는 draft, preview, read-first bridge를 보여줄 수 있다. 하지만 실제 대화 런타임을 앱 API 안에 새로 만들면 OkayJing이 두 개의 대화 시스템을 갖게 된다. 이건 피해야 한다.

개인 agent workspace를 웹앱으로 만들면 모든 것을 API로 만들고 싶어진다. 하지만 chat, voice, approval, media routing까지 새 앱 API로 다시 만들면 기존 agent gateway와 겹친다. 반대로 DB, Markdown, ticket처럼 여러 표면이 동시에 만지는 원천 리소스는 API 없이 직접 고치면 충돌이 난다.

기준은 "상태 변경의 소유자"다. 여러 클라이언트가 같은 원천 리소스를 바꾼다면 API가 잠금, 검증, diff, audit log를 맡는다. 이미 gateway가 잘 처리하는 대화와 승인 흐름은 재구현하지 말고 bridge로 연결한다. 이렇게 나누면 웹앱은 상태를 안전하게 바꾸고, agent runtime은 대화 의미를 계속 맡는다.