triflux 3.0.0 → 3.1.0-dev.2

package/.mcp.json

@@ -1,3 +1,8 @@
-{
-  "mcpServers": {}
-}
+{
+  "mcpServers": {
+    "tfx-hub": {
+      "type": "url",
+      "url": "http://127.0.0.1:27888/mcp"
+    }
+  }
+}

package/bin/triflux.mjs

@@ -3,7 +3,7 @@
 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");
@@ -221,6 +221,13 @@ function cmdSetup() {
     }
   }
 
+  // hub MCP 사전 등록 (서버 미실행이어도 설정만 등록 — hub start 시 즉시 사용 가능)
+  if (existsSync(join(PKG_ROOT, "hub", "server.mjs"))) {
+    const defaultHubUrl = `http://127.0.0.1:${process.env.TFX_HUB_PORT || "27888"}/mcp`;
+    autoRegisterMcp(defaultHubUrl);
+    console.log("");
+  }
+
   // HUD statusLine 설정
   console.log(`${CYAN}[HUD 설정]${RESET}`);
   const settingsPath = join(CLAUDE_DIR, "settings.json");
@@ -578,7 +585,9 @@ function cmdDoctor(options = {}) {
 }
 
 function cmdUpdate() {
-  console.log(`\n${BOLD}triflux update${RESET}\n`);
+  const isDev = process.argv.includes("--dev");
+  const tagLabel = isDev ? ` ${YELLOW}@dev${RESET}` : "";
+  console.log(`\n${BOLD}triflux update${RESET}${tagLabel}\n`);
 
   // 1. 설치 방식 감지
   const pluginsFile = join(CLAUDE_DIR, "plugins", "installed_plugins.json");
@@ -648,17 +657,19 @@ function cmdUpdate() {
         break;
       }
       case "npm-global": {
-        const result = execSync("npm update -g triflux", {
+        const npmCmd = isDev ? "npm install -g triflux@dev" : "npm update -g triflux";
+        const result = execSync(npmCmd, {
           encoding: "utf8",
           timeout: 60000,
           stdio: ["pipe", "pipe", "ignore"],
         }).trim().split(/\r?\n/)[0];
-        ok(`npm update -g — ${result || "완료"}`);
+        ok(`${isDev ? "npm install -g @dev" : "npm update -g"} — ${result || "완료"}`);
         updated = true;
         break;
       }
       case "npm-local": {
-        const result = execSync("npm update triflux", {
+        const npmLocalCmd = isDev ? "npm install triflux@dev" : "npm update triflux";
+        const result = execSync(npmLocalCmd, {
           encoding: "utf8",
           timeout: 60000,
           cwd: process.cwd(),
@@ -812,7 +823,9 @@ ${updateNotice}
     ${DIM}  --fix${RESET}        ${GRAY}진단 + 자동 수정${RESET}
     ${DIM}  --reset${RESET}      ${GRAY}캐시 전체 초기화${RESET}
     ${WHITE_BRIGHT}tfx update${RESET}     ${GRAY}최신 버전으로 업데이트${RESET}
+    ${DIM}  --dev${RESET}         ${GRAY}dev 태그로 업데이트${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}
 
@@ -829,6 +842,209 @@ ${updateNotice}
 `);
 }
 
+// ── hub 서브커맨드 ──
+
+const HUB_PID_DIR = join(homedir(), ".claude", "cache", "tfx-hub");
+const HUB_PID_FILE = join(HUB_PID_DIR, "hub.pid");
+
+// 설치된 CLI에 tfx-hub MCP 서버 자동 등록 (1회 설정, 이후 재실행 불필요)
+function autoRegisterMcp(mcpUrl) {
+  section("MCP 자동 등록");
+
+  // Codex — codex mcp add
+  if (which("codex")) {
+    try {
+      // 이미 등록됐는지 확인
+      const list = execSync("codex mcp list 2>&1", { encoding: "utf8", timeout: 10000, stdio: ["pipe", "pipe", "pipe"] });
+      if (list.includes("tfx-hub")) {
+        ok("Codex: 이미 등록됨");
+      } else {
+        execSync(`codex mcp add tfx-hub --url ${mcpUrl}`, { timeout: 10000, stdio: "ignore" });
+        ok("Codex: MCP 등록 완료");
+      }
+    } catch {
+      // mcp list/add 미지원 → 설정 파일 직접 수정
+      try {
+        const codexDir = join(homedir(), ".codex");
+        const configFile = join(codexDir, "config.json");
+        let config = {};
+        if (existsSync(configFile)) config = JSON.parse(readFileSync(configFile, "utf8"));
+        if (!config.mcpServers) config.mcpServers = {};
+        if (!config.mcpServers["tfx-hub"]) {
+          config.mcpServers["tfx-hub"] = { url: mcpUrl };
+          if (!existsSync(codexDir)) mkdirSync(codexDir, { recursive: true });
+          writeFileSync(configFile, JSON.stringify(config, null, 2) + "\n");
+          ok("Codex: config.json에 등록 완료");
+        } else {
+          ok("Codex: 이미 등록됨");
+        }
+      } catch (e) { warn(`Codex 등록 실패: ${e.message}`); }
+    }
+  } else {
+    info("Codex: 미설치 (건너뜀)");
+  }
+
+  // Gemini — settings.json 직접 수정
+  if (which("gemini")) {
+    try {
+      const geminiDir = join(homedir(), ".gemini");
+      const settingsFile = join(geminiDir, "settings.json");
+      let settings = {};
+      if (existsSync(settingsFile)) settings = JSON.parse(readFileSync(settingsFile, "utf8"));
+      if (!settings.mcpServers) settings.mcpServers = {};
+      if (!settings.mcpServers["tfx-hub"]) {
+        settings.mcpServers["tfx-hub"] = { url: mcpUrl };
+        if (!existsSync(geminiDir)) mkdirSync(geminiDir, { recursive: true });
+        writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + "\n");
+        ok("Gemini: settings.json에 등록 완료");
+      } else {
+        ok("Gemini: 이미 등록됨");
+      }
+    } catch (e) { warn(`Gemini 등록 실패: ${e.message}`); }
+  } else {
+    info("Gemini: 미설치 (건너뜀)");
+  }
+
+  // Claude — 프로젝트 .mcp.json에 등록 (오케스트레이터용)
+  try {
+    const mcpJsonPath = join(PKG_ROOT, ".mcp.json");
+    let mcpJson = {};
+    if (existsSync(mcpJsonPath)) mcpJson = JSON.parse(readFileSync(mcpJsonPath, "utf8"));
+    if (!mcpJson.mcpServers) mcpJson.mcpServers = {};
+    if (!mcpJson.mcpServers["tfx-hub"]) {
+      mcpJson.mcpServers["tfx-hub"] = { type: "url", url: mcpUrl };
+      writeFileSync(mcpJsonPath, JSON.stringify(mcpJson, null, 2) + "\n");
+      ok("Claude: .mcp.json에 등록 완료");
+    } else {
+      ok("Claude: 이미 등록됨");
+    }
+  } catch (e) { warn(`Claude 등록 실패: ${e.message}`); }
+}
+
+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 hubInfo = JSON.parse(readFileSync(HUB_PID_FILE, "utf8"));
+        console.log(`\n  ${GREEN_BRIGHT}✓${RESET} ${BOLD}tfx-hub 시작${RESET}`);
+        console.log(`    URL:  ${AMBER}${hubInfo.url}${RESET}`);
+        console.log(`    PID:  ${hubInfo.pid}`);
+        console.log(`    DB:   ${DIM}${HUB_PID_DIR}/state.db${RESET}`);
+        console.log("");
+        autoRegisterMcp(hubInfo.url);
+        console.log("");
+      } 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}"`, { encoding: "utf8", timeout: 3000, stdio: ["pipe", "pipe", "ignore"] });
+          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";
@@ -843,6 +1059,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);