triflux 2.5.1 → 3.1.0-dev.1

package/bin/triflux.mjs

@@ -1,9 +1,9 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 // triflux CLI — setup, doctor, version
 import { copyFileSync, existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, readdirSync, unlinkSync } from "fs";
 import { join, dirname } from "path";
 import { homedir } from "os";
-import { execSync } from "child_process";
+import { execSync, spawn } from "child_process";
 
 const PKG_ROOT = dirname(dirname(new URL(import.meta.url).pathname)).replace(/^\/([A-Z]:)/, "$1");
 const CLAUDE_DIR = join(homedir(), ".claude");
@@ -145,7 +145,7 @@ function checkCliCrossShell(cmd, installHint) {
     return 1;
   }
   if (bashMissing) {
-    warn("bash에서 미발견 — cli-route.sh 실행 불가");
+    warn("bash에서 미발견 — tfx-route.sh 실행 불가");
     info('→ ~/.bashrc에 추가: export PATH="$PATH:$APPDATA/npm"');
     return 1;
   }
@@ -158,9 +158,9 @@ function cmdSetup() {
   console.log(`\n${BOLD}triflux setup${RESET}\n`);
 
   syncFile(
-    join(PKG_ROOT, "scripts", "cli-route.sh"),
-    join(CLAUDE_DIR, "scripts", "cli-route.sh"),
-    "cli-route.sh"
+    join(PKG_ROOT, "scripts", "tfx-route.sh"),
+    join(CLAUDE_DIR, "scripts", "tfx-route.sh"),
+    "tfx-route.sh"
   );
 
   syncFile(
@@ -175,6 +175,18 @@ function cmdSetup() {
     "notion-read.mjs"
   );
 
+  syncFile(
+    join(PKG_ROOT, "scripts", "tfx-route-post.mjs"),
+    join(CLAUDE_DIR, "scripts", "tfx-route-post.mjs"),
+    "tfx-route-post.mjs"
+  );
+
+  syncFile(
+    join(PKG_ROOT, "scripts", "tfx-batch-stats.mjs"),
+    join(CLAUDE_DIR, "scripts", "tfx-batch-stats.mjs"),
+    "tfx-batch-stats.mjs"
+  );
+
   // 스킬 동기화 (~/.claude/skills/{name}/SKILL.md)
   const skillsSrc = join(PKG_ROOT, "skills");
   const skillsDst = join(CLAUDE_DIR, "skills");
@@ -323,9 +335,9 @@ function cmdDoctor(options = {}) {
   if (fix) {
     section("Auto Fix");
     syncFile(
-      join(PKG_ROOT, "scripts", "cli-route.sh"),
-      join(CLAUDE_DIR, "scripts", "cli-route.sh"),
-      "cli-route.sh"
+      join(PKG_ROOT, "scripts", "tfx-route.sh"),
+      join(CLAUDE_DIR, "scripts", "tfx-route.sh"),
+      "tfx-route.sh"
     );
     syncFile(
       join(PKG_ROOT, "hud", "hud-qos-status.mjs"),
@@ -375,9 +387,9 @@ function cmdDoctor(options = {}) {
 
   let issues = 0;
 
-  // 1. cli-route.sh
-  section("cli-route.sh");
-  const routeSh = join(CLAUDE_DIR, "scripts", "cli-route.sh");
+  // 1. tfx-route.sh
+  section("tfx-route.sh");
+  const routeSh = join(CLAUDE_DIR, "scripts", "tfx-route.sh");
   if (existsSync(routeSh)) {
     const ver = getVersion(routeSh);
     ok(`설치됨 ${ver ? `${DIM}v${ver}${RESET}` : ""}`);
@@ -676,7 +688,7 @@ function cmdUpdate() {
     return;
   }
 
-  // 3. setup 재실행 (cli-route.sh, HUD, 스킬 동기화)
+  // 3. setup 재실행 (tfx-route.sh, HUD, 스킬 동기화)
   if (updated) {
     console.log("");
     // 업데이트 후 새 버전 읽기
@@ -742,10 +754,10 @@ function cmdList() {
 }
 
 function cmdVersion() {
-  const routeVer = getVersion(join(CLAUDE_DIR, "scripts", "cli-route.sh"));
+  const routeVer = getVersion(join(CLAUDE_DIR, "scripts", "tfx-route.sh"));
   const hudVer = getVersion(join(CLAUDE_DIR, "hud", "hud-qos-status.mjs"));
   console.log(`\n  ${AMBER}${BOLD}⬡ triflux${RESET} ${WHITE_BRIGHT}v${PKG.version}${RESET}`);
-  if (routeVer) console.log(`  ${GRAY}cli-route${RESET}  v${routeVer}`);
+  if (routeVer) console.log(`  ${GRAY}tfx-route${RESET}  v${routeVer}`);
   if (hudVer) console.log(`  ${GRAY}hud${RESET}        v${hudVer}`);
   console.log("");
 }
@@ -801,6 +813,7 @@ ${updateNotice}
     ${DIM}  --reset${RESET}      ${GRAY}캐시 전체 초기화${RESET}
     ${WHITE_BRIGHT}tfx update${RESET}     ${GRAY}최신 버전으로 업데이트${RESET}
     ${WHITE_BRIGHT}tfx list${RESET}       ${GRAY}설치된 스킬 목록${RESET}
+    ${WHITE_BRIGHT}tfx hub${RESET}        ${GRAY}MCP 메시지 버스 관리 (start/stop/status)${RESET}
     ${WHITE_BRIGHT}tfx notion-read${RESET} ${GRAY}Notion 페이지 → 마크다운 (Codex/Gemini MCP)${RESET}
     ${WHITE_BRIGHT}tfx version${RESET}    ${GRAY}버전 표시${RESET}
 
@@ -817,6 +830,132 @@ ${updateNotice}
 `);
 }
 
+// ── hub 서브커맨드 ──
+
+const HUB_PID_DIR = join(homedir(), ".claude", "cache", "tfx-hub");
+const HUB_PID_FILE = join(HUB_PID_DIR, "hub.pid");
+
+function cmdHub() {
+  const sub = process.argv[3] || "status";
+
+  switch (sub) {
+    case "start": {
+      // 이미 실행 중인지 확인
+      if (existsSync(HUB_PID_FILE)) {
+        try {
+          const info = JSON.parse(readFileSync(HUB_PID_FILE, "utf8"));
+          process.kill(info.pid, 0); // 프로세스 존재 확인
+          console.log(`\n  ${YELLOW}⚠${RESET} hub 이미 실행 중 (PID ${info.pid}, ${info.url})\n`);
+          return;
+        } catch {
+          // PID 파일 있지만 프로세스 없음 — 정리
+          try { unlinkSync(HUB_PID_FILE); } catch {}
+        }
+      }
+
+      const portArg = process.argv.indexOf("--port");
+      const port = portArg !== -1 ? process.argv[portArg + 1] : "27888";
+      const serverPath = join(PKG_ROOT, "hub", "server.mjs");
+
+      if (!existsSync(serverPath)) {
+        fail("hub/server.mjs 없음 — hub 모듈이 설치되지 않음");
+        return;
+      }
+
+      const child = spawn(process.execPath, [serverPath], {
+        env: { ...process.env, TFX_HUB_PORT: port },
+        stdio: "ignore",
+        detached: true,
+      });
+      child.unref();
+
+      // PID 파일 확인 (최대 3초 대기, 100ms 폴링)
+      let started = false;
+      const deadline = Date.now() + 3000;
+      while (Date.now() < deadline) {
+        if (existsSync(HUB_PID_FILE)) { started = true; break; }
+        execSync("node -e \"setTimeout(()=>{},100)\"", { stdio: "ignore", timeout: 500 });
+      }
+
+      if (started) {
+        const info = JSON.parse(readFileSync(HUB_PID_FILE, "utf8"));
+        console.log(`\n  ${GREEN_BRIGHT}✓${RESET} ${BOLD}tfx-hub 시작${RESET}`);
+        console.log(`    URL:  ${AMBER}${info.url}${RESET}`);
+        console.log(`    PID:  ${info.pid}`);
+        console.log(`    DB:   ${DIM}${HUB_PID_DIR}/state.db${RESET}\n`);
+      } else {
+        // 직접 포그라운드 모드로 안내
+        console.log(`\n  ${YELLOW}⚠${RESET} 백그라운드 시작 실패 — 포그라운드로 실행:`);
+        console.log(`    ${DIM}TFX_HUB_PORT=${port} node ${serverPath}${RESET}\n`);
+      }
+      break;
+    }
+
+    case "stop": {
+      if (!existsSync(HUB_PID_FILE)) {
+        console.log(`\n  ${DIM}hub 미실행${RESET}\n`);
+        return;
+      }
+      try {
+        const info = JSON.parse(readFileSync(HUB_PID_FILE, "utf8"));
+        process.kill(info.pid, "SIGTERM");
+        try { unlinkSync(HUB_PID_FILE); } catch {}
+        console.log(`\n  ${GREEN_BRIGHT}✓${RESET} hub 종료됨 (PID ${info.pid})\n`);
+      } catch (e) {
+        try { unlinkSync(HUB_PID_FILE); } catch {}
+        console.log(`\n  ${DIM}hub 프로세스 없음 — PID 파일 정리됨${RESET}\n`);
+      }
+      break;
+    }
+
+    case "status": {
+      if (!existsSync(HUB_PID_FILE)) {
+        console.log(`\n  ${AMBER}${BOLD}⬡ tfx-hub${RESET} ${RED}offline${RESET}\n`);
+        return;
+      }
+      try {
+        const info = JSON.parse(readFileSync(HUB_PID_FILE, "utf8"));
+        process.kill(info.pid, 0); // 생존 확인
+        const uptime = Date.now() - info.started;
+        const uptimeStr = uptime < 60000 ? `${Math.round(uptime / 1000)}초`
+          : uptime < 3600000 ? `${Math.round(uptime / 60000)}분`
+          : `${Math.round(uptime / 3600000)}시간`;
+
+        console.log(`\n  ${AMBER}${BOLD}⬡ tfx-hub${RESET} ${GREEN_BRIGHT}online${RESET}`);
+        console.log(`    URL:     ${info.url}`);
+        console.log(`    PID:     ${info.pid}`);
+        console.log(`    Uptime:  ${uptimeStr}`);
+
+        // HTTP 상태 조회 시도
+        try {
+          const statusUrl = info.url.replace("/mcp", "/status");
+          const result = execSync(`curl -s "${statusUrl}" 2>/dev/null`, { encoding: "utf8", timeout: 3000 });
+          const data = JSON.parse(result);
+          if (data.hub) {
+            console.log(`    State:   ${data.hub.state}`);
+          }
+          if (data.sessions !== undefined) {
+            console.log(`    Sessions: ${data.sessions}`);
+          }
+        } catch {}
+
+        console.log("");
+      } catch {
+        try { unlinkSync(HUB_PID_FILE); } catch {}
+        console.log(`\n  ${AMBER}${BOLD}⬡ tfx-hub${RESET} ${RED}offline${RESET} ${DIM}(stale PID 정리됨)${RESET}\n`);
+      }
+      break;
+    }
+
+    default:
+      console.log(`\n  ${AMBER}${BOLD}⬡ tfx-hub${RESET}\n`);
+      console.log(`    ${WHITE_BRIGHT}tfx hub start${RESET}   ${GRAY}허브 데몬 시작${RESET}`);
+      console.log(`    ${DIM}  --port N${RESET}      ${GRAY}포트 지정 (기본 27888)${RESET}`);
+      console.log(`    ${WHITE_BRIGHT}tfx hub stop${RESET}    ${GRAY}허브 중지${RESET}`);
+      console.log(`    ${WHITE_BRIGHT}tfx hub status${RESET}  ${GRAY}상태 확인${RESET}\n`);
+  }
+}
+
 // ── 메인 ──
 
 const cmd = process.argv[2] || "help";
@@ -831,6 +970,7 @@ switch (cmd) {
   }
   case "update":  cmdUpdate(); break;
   case "list": case "ls": cmdList(); break;
+  case "hub":     cmdHub(); break;
   case "notion-read": case "nr": {
     const scriptPath = join(PKG_ROOT, "scripts", "notion-read.mjs");
     const nrArgs = process.argv.slice(3).map(a => `"${a}"`).join(" ");

package/hub/hitl.mjs

@@ -0,0 +1,130 @@
+// hub/hitl.mjs — Human-in-the-Loop 매니저
+// 사용자 입력 요청/응답, 타임아웃 자동 처리
+import { uuidv7 } from './store.mjs';
+
+/**
+ * HITL 매니저 생성
+ * @param {object} store — createStore() 반환 객체
+ */
+export function createHitlManager(store) {
+  return {
+    /**
+     * 사용자에게 입력 요청 생성
+     * 터미널에 알림 출력 후 pending 상태로 저장
+     */
+    requestHumanInput({
+      requester_agent, kind, prompt, requested_schema = {},
+      deadline_ms, default_action, channel_preference = 'terminal',
+      correlation_id, trace_id,
+    }) {
+      const result = store.insertHumanRequest({
+        requester_agent, kind, prompt, requested_schema,
+        deadline_ms, default_action,
+        correlation_id, trace_id,
+      });
+
+      // 터미널 알림 (stderr — stdout은 MCP 용)
+      const kindLabel = { captcha: 'CAPTCHA', approval: '승인', credential: '자격증명', choice: '선택', text: '텍스트' };
+      process.stderr.write(
+        `\n[tfx-hub] 사용자 입력 요청 (${kindLabel[kind] || kind})\n` +
+        `  요청자: ${requester_agent}\n` +
+        `  내용: ${prompt}\n` +
+        `  ID: ${result.request_id}\n` +
+        `  제한: ${Math.round(deadline_ms / 1000)}초\n\n`,
+      );
+
+      return { ok: true, data: result };
+    },
+
+    /**
+     * 사용자 입력 응답 제출
+     * 유효성 검증 → 상태 업데이트 → 요청자에게 응답 메시지 전달
+     */
+    submitHumanInput({ request_id, action, content = null, submitted_by = 'human' }) {
+      // 요청 조회
+      const hr = store.getHumanRequest(request_id);
+      if (!hr) {
+        return { ok: false, error: { code: 'NOT_FOUND', message: `요청 없음: ${request_id}` } };
+      }
+      if (hr.state !== 'pending') {
+        return { ok: false, error: { code: 'ALREADY_HANDLED', message: `이미 처리됨: ${hr.state}` } };
+      }
+
+      // 상태 매핑
+      const stateMap = { accept: 'accepted', decline: 'declined', cancel: 'cancelled' };
+      const newState = stateMap[action];
+      if (!newState) {
+        return { ok: false, error: { code: 'INVALID_ACTION', message: `잘못된 action: ${action}` } };
+      }
+
+      // DB 업데이트
+      store.updateHumanRequest(request_id, newState, content);
+
+      // 요청자에게 응답 메시지 전달
+      let forwardedMessageId = null;
+      if (action === 'accept' || action === 'decline') {
+        const msg = store.enqueueMessage({
+          type: 'human_response',
+          from: 'hub:hitl',
+          to: hr.requester_agent,
+          topic: 'human.response',
+          priority: 7, // urgent — 사용자 블로킹 해소
+          ttl_ms: 300000,
+          payload: { request_id, action, content, submitted_by },
+          correlation_id: hr.correlation_id,
+          trace_id: hr.trace_id,
+        });
+        store.deliverToAgent(msg.id, hr.requester_agent);
+        forwardedMessageId = msg.id;
+      }
+
+      return {
+        ok: true,
+        data: { request_id, new_state: newState, forwarded_message_id: forwardedMessageId },
+      };
+    },
+
+    /**
+     * 만료된 요청 자동 처리
+     * deadline 초과 시 default_action 적용
+     */
+    checkTimeouts() {
+      const pending = store.getPendingHumanRequests();
+      const now = Date.now();
+      let processed = 0;
+
+      for (const hr of pending) {
+        if (hr.deadline_ms > now) continue;
+
+        // default_action 적용
+        if (hr.default_action === 'timeout_continue') {
+          store.updateHumanRequest(hr.request_id, 'timed_out', null);
+          // 요청자에게 타임아웃 알림
+          const msg = store.enqueueMessage({
+            type: 'human_response',
+            from: 'hub:hitl',
+            to: hr.requester_agent,
+            topic: 'human.response',
+            priority: 5,
+            ttl_ms: 300000,
+            payload: { request_id: hr.request_id, action: 'timeout_continue', content: null },
+            correlation_id: hr.correlation_id,
+            trace_id: hr.trace_id,
+          });
+          store.deliverToAgent(msg.id, hr.requester_agent);
+        } else {
+          // decline 또는 cancel
+          store.updateHumanRequest(hr.request_id, 'timed_out', null);
+        }
+        processed++;
+      }
+
+      return processed;
+    },
+
+    /** 대기 중인 요청 목록 */
+    getPendingRequests() {
+      return store.getPendingHumanRequests();
+    },
+  };
+}

package/hub/router.mjs

@@ -0,0 +1,189 @@
+// hub/router.mjs — Actor mailbox 라우터 + QoS 스케줄러
+// 메시지 라우팅, ask/publish/handoff 처리, TTL 정리
+import { uuidv7 } from './store.mjs';
+
+/**
+ * 라우터 생성
+ * @param {object} store — createStore() 반환 객체
+ */
+export function createRouter(store) {
+  let sweepTimer = null;
+  let staleTimer = null;
+
+  const router = {
+    /**
+     * 메시지를 대상에게 라우팅
+     * "topic:XXX" → 토픽 구독자 전체 fanout
+     * 직접 agent_id → 1:1 배달
+     * @returns {number} 배달된 에이전트 수
+     */
+    route(msg) {
+      const to = msg.to_agent ?? msg.to;
+      if (to.startsWith('topic:')) {
+        return store.deliverToTopic(msg.id, to.slice(6));
+      }
+      store.deliverToAgent(msg.id, to);
+      return 1;
+    },
+
+    /**
+     * ask — 질문 요청 (request/reply 패턴)
+     * await_response_ms > 0 이면 짧은 폴링으로 응답 대기
+     * 0 이면 티켓(correlation_id) 즉시 반환
+     */
+    async handleAsk({
+      from, to, topic, question, context_refs,
+      payload = {}, priority = 5, ttl_ms = 300000,
+      await_response_ms = 0, trace_id, correlation_id,
+    }) {
+      const cid = correlation_id || uuidv7();
+      const tid = trace_id || uuidv7();
+
+      const msg = store.enqueueMessage({
+        type: 'request', from, to, topic, priority, ttl_ms,
+        payload: { question, context_refs, ...payload },
+        correlation_id: cid, trace_id: tid,
+      });
+      router.route(msg);
+
+      // 티켓 모드: 즉시 반환
+      if (await_response_ms <= 0) {
+        return {
+          ok: true,
+          data: { request_message_id: msg.id, correlation_id: cid, trace_id: tid, state: 'queued' },
+        };
+      }
+
+      // 짧은 폴링 대기 (최대 30초 제한)
+      const deadline = Date.now() + Math.min(await_response_ms, 30000);
+      while (Date.now() < deadline) {
+        const resp = store.getResponseByCorrelation(cid);
+        if (resp) {
+          return {
+            ok: true,
+            data: { request_message_id: msg.id, correlation_id: cid, trace_id: tid, state: 'answered', response: resp.payload },
+          };
+        }
+        await new Promise(r => setTimeout(r, 100));
+      }
+
+      // 타임아웃 — 티켓 반환
+      return {
+        ok: true,
+        data: { request_message_id: msg.id, correlation_id: cid, trace_id: tid, state: 'delivered' },
+      };
+    },
+
+    /**
+     * publish — 이벤트/응답 발행
+     * correlation_id 존재 시 response 타입, 없으면 event 타입
+     */
+    handlePublish({
+      from, to, topic, priority = 5, ttl_ms = 300000,
+      payload = {}, trace_id, correlation_id,
+    }) {
+      const type = correlation_id ? 'response' : 'event';
+      const msg = store.enqueueMessage({
+        type, from, to, topic, priority, ttl_ms, payload,
+        correlation_id: correlation_id || uuidv7(),
+        trace_id: trace_id || uuidv7(),
+      });
+      const fanout = router.route(msg);
+      return {
+        ok: true,
+        data: { message_id: msg.id, fanout_count: fanout, expires_at_ms: msg.expires_at_ms },
+      };
+    },
+
+    /**
+     * handoff — 작업 인계
+     * acceptance_criteria, context_refs 포함 가능
+     */
+    handleHandoff({
+      from, to, topic, task, acceptance_criteria, context_refs,
+      priority = 5, ttl_ms = 600000, trace_id, correlation_id,
+    }) {
+      const msg = store.enqueueMessage({
+        type: 'handoff', from, to, topic, priority, ttl_ms,
+        payload: { task, acceptance_criteria, context_refs },
+        correlation_id: correlation_id || uuidv7(),
+        trace_id: trace_id || uuidv7(),
+      });
+      router.route(msg);
+      return {
+        ok: true,
+        data: { handoff_message_id: msg.id, state: 'queued', assigned_to: to },
+      };
+    },
+
+    // ── 스위퍼 ──
+
+    /** 주기적 만료 정리 시작 (1초: 메시지, 60초: 비활성 에이전트) */
+    startSweeper() {
+      if (sweepTimer) return;
+      sweepTimer = setInterval(() => {
+        try { store.sweepExpired(); } catch { /* 무시 */ }
+      }, 1000);
+      staleTimer = setInterval(() => {
+        try { store.sweepStaleAgents(); } catch { /* 무시 */ }
+      }, 60000);
+      sweepTimer.unref();
+      staleTimer.unref();
+    },
+
+    /** 정리 중지 */
+    stopSweeper() {
+      if (sweepTimer) { clearInterval(sweepTimer); sweepTimer = null; }
+      if (staleTimer) { clearInterval(staleTimer); staleTimer = null; }
+    },
+
+    // ── 상태 조회 ──
+
+    /**
+     * 허브/에이전트/큐/트레이스 상태 조회
+     * @param {'hub'|'agent'|'queue'|'trace'} scope
+     */
+    getStatus(scope = 'hub', { agent_id, trace_id, include_metrics = true } = {}) {
+      const data = {};
+
+      if (scope === 'hub' || scope === 'queue') {
+        data.hub = {
+          state: 'healthy',
+          uptime_ms: process.uptime() * 1000 | 0,
+          db_wal_mode: true,
+        };
+        if (include_metrics) {
+          const depths = store.getQueueDepths();
+          const stats = store.getDeliveryStats();
+          data.queues = {
+            urgent_depth: depths.urgent,
+            normal_depth: depths.normal,
+            dlq_depth: depths.dlq,
+            p95_delivery_ms: stats.avg_delivery_ms,
+            timeout_rate: 0,
+          };
+        }
+      }
+
+      if (scope === 'agent' && agent_id) {
+        const agent = store.getAgent(agent_id);
+        if (agent) {
+          data.agent = {
+            agent_id: agent.agent_id,
+            status: agent.status,
+            pending: 0,
+            last_seen_ms: agent.last_seen_ms,
+          };
+        }
+      }
+
+      if (scope === 'trace' && trace_id) {
+        data.trace = store.getMessagesByTrace(trace_id);
+      }
+
+      return { ok: true, data };
+    },
+  };
+
+  return router;
+}

package/hub/schema.sql

@@ -0,0 +1,80 @@
+-- tfx-hub 상태 저장소 스키마
+-- SQLite WAL 모드 기반 메시지 버스
+
+-- 에이전트 등록 테이블
+CREATE TABLE IF NOT EXISTS agents (
+  agent_id TEXT PRIMARY KEY,
+  cli TEXT NOT NULL CHECK (cli IN ('codex','gemini','claude','other')),
+  pid INTEGER,
+  capabilities_json TEXT NOT NULL DEFAULT '[]',
+  topics_json TEXT NOT NULL DEFAULT '[]',
+  last_seen_ms INTEGER NOT NULL,
+  lease_expires_ms INTEGER NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('online','stale','offline')),
+  metadata_json TEXT NOT NULL DEFAULT '{}'
+);
+
+-- 메시지 테이블
+CREATE TABLE IF NOT EXISTS messages (
+  id TEXT PRIMARY KEY,
+  type TEXT NOT NULL CHECK (type IN ('request','response','event','handoff','human_request','human_response','system')),
+  from_agent TEXT NOT NULL,
+  to_agent TEXT NOT NULL,
+  topic TEXT NOT NULL,
+  priority INTEGER NOT NULL CHECK (priority BETWEEN 1 AND 9),
+  ttl_ms INTEGER NOT NULL,
+  created_at_ms INTEGER NOT NULL,
+  expires_at_ms INTEGER NOT NULL,
+  correlation_id TEXT NOT NULL,
+  trace_id TEXT NOT NULL,
+  payload_json TEXT NOT NULL DEFAULT '{}',
+  status TEXT NOT NULL CHECK (status IN ('queued','delivered','acked','expired','dead_letter'))
+);
+
+-- 메시지 수신함 (배달 추적)
+CREATE TABLE IF NOT EXISTS message_inbox (
+  delivery_id INTEGER PRIMARY KEY AUTOINCREMENT,
+  message_id TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  delivered_at_ms INTEGER,
+  acked_at_ms INTEGER,
+  attempts INTEGER NOT NULL DEFAULT 0,
+  UNIQUE(message_id, agent_id),
+  FOREIGN KEY(message_id) REFERENCES messages(id) ON DELETE CASCADE
+);
+
+-- 사용자 입력 요청 테이블
+CREATE TABLE IF NOT EXISTS human_requests (
+  request_id TEXT PRIMARY KEY,
+  requester_agent TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK (kind IN ('captcha','approval','credential','choice','text')),
+  prompt TEXT NOT NULL,
+  schema_json TEXT NOT NULL DEFAULT '{}',
+  state TEXT NOT NULL CHECK (state IN ('pending','accepted','declined','cancelled','timed_out')),
+  deadline_ms INTEGER NOT NULL,
+  default_action TEXT NOT NULL CHECK (default_action IN ('decline','cancel','timeout_continue')),
+  correlation_id TEXT NOT NULL,
+  trace_id TEXT NOT NULL,
+  response_json TEXT
+);
+
+-- 데드 레터 큐
+CREATE TABLE IF NOT EXISTS dead_letters (
+  message_id TEXT PRIMARY KEY,
+  reason TEXT NOT NULL,
+  failed_at_ms INTEGER NOT NULL,
+  last_error TEXT
+);
+
+-- 인덱스
+CREATE INDEX IF NOT EXISTS idx_messages_status ON messages(status);
+CREATE INDEX IF NOT EXISTS idx_messages_to_agent ON messages(to_agent, status);
+CREATE INDEX IF NOT EXISTS idx_messages_correlation ON messages(correlation_id);
+CREATE INDEX IF NOT EXISTS idx_messages_trace ON messages(trace_id);
+CREATE INDEX IF NOT EXISTS idx_messages_expires ON messages(expires_at_ms);
+CREATE INDEX IF NOT EXISTS idx_messages_priority ON messages(priority DESC, created_at_ms ASC);
+CREATE INDEX IF NOT EXISTS idx_inbox_agent ON message_inbox(agent_id, delivered_at_ms);
+CREATE INDEX IF NOT EXISTS idx_inbox_message ON message_inbox(message_id);
+CREATE INDEX IF NOT EXISTS idx_human_requests_state ON human_requests(state);
+CREATE INDEX IF NOT EXISTS idx_agents_status ON agents(status);
+CREATE INDEX IF NOT EXISTS idx_agents_lease ON agents(lease_expires_ms);