triflux 3.1.0-dev.2 → 3.1.0-dev.4

package/hub/bridge.mjs

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+// hub/bridge.mjs — tfx-route.sh ↔ tfx-hub 브릿지 CLI
+//
+// tfx-route.sh에서 CLI 에이전트 실행 전후로 호출하여
+// Hub에 자동 등록/결과 발행/컨텍스트 수신/해제를 수행한다.
+//
+// 사용법:
+//   node bridge.mjs register  --agent <id> --cli <type> --timeout <sec> [--topics t1,t2]
+//   node bridge.mjs result    --agent <id> --file <path> [--topic task.result] [--trace <id>]
+//   node bridge.mjs context   --agent <id> [--topics t1,t2] [--max 10] [--out <path>]
+//   node bridge.mjs deregister --agent <id>
+//   node bridge.mjs ping
+//
+// Hub 미실행 시 모든 커맨드는 조용히 실패 (exit 0).
+// tfx-route.sh 흐름을 절대 차단하지 않는다.
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { parseArgs as nodeParseArgs } from 'node:util';
+
+const HUB_PID_FILE = join(homedir(), '.claude', 'cache', 'tfx-hub', 'hub.pid');
+
+// ── Hub URL 해석 ──
+
+function getHubUrl() {
+  // 환경변수 우선
+  if (process.env.TFX_HUB_URL) return process.env.TFX_HUB_URL.replace(/\/mcp$/, '');
+
+  // PID 파일에서 읽기
+  if (existsSync(HUB_PID_FILE)) {
+    try {
+      const info = JSON.parse(readFileSync(HUB_PID_FILE, 'utf8'));
+      return `http://${info.host || '127.0.0.1'}:${info.port || 27888}`;
+    } catch { /* 무시 */ }
+  }
+
+  // 기본값
+  const port = process.env.TFX_HUB_PORT || '27888';
+  return `http://127.0.0.1:${port}`;
+}
+
+const _cachedHubUrl = getHubUrl();
+
+// ── HTTP 요청 ──
+
+async function post(path, body, timeoutMs = 5000) {
+  const url = `${_cachedHubUrl}${path}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    clearTimeout(timer);
+    return await res.json();
+  } catch {
+    clearTimeout(timer);
+    return null; // Hub 미실행 — 조용히 실패
+  }
+}
+
+// ── 인자 파싱 ──
+
+function parseArgs(argv) {
+  const { values } = nodeParseArgs({
+    args: argv,
+    options: {
+      agent: { type: 'string' },
+      cli: { type: 'string' },
+      timeout: { type: 'string' },
+      topics: { type: 'string' },
+      capabilities: { type: 'string' },
+      file: { type: 'string' },
+      topic: { type: 'string' },
+      trace: { type: 'string' },
+      correlation: { type: 'string' },
+      'exit-code': { type: 'string' },
+      max: { type: 'string' },
+      out: { type: 'string' },
+    },
+    strict: false,
+  });
+  return values;
+}
+
+// ── 커맨드 ──
+
+async function cmdRegister(args) {
+  const agentId = args.agent;
+  const cli = args.cli || 'other';
+  const timeoutSec = parseInt(args.timeout || '600', 10);
+  const topics = args.topics ? args.topics.split(',') : [];
+  const capabilities = args.capabilities ? args.capabilities.split(',') : ['code'];
+
+  const result = await post('/bridge/register', {
+    agent_id: agentId,
+    cli,
+    timeout_sec: timeoutSec,
+    topics,
+    capabilities,
+    metadata: {
+      pid: process.ppid, // 부모 프로세스 (tfx-route.sh)
+      registered_at: Date.now(),
+    },
+  });
+
+  if (result?.ok) {
+    // 에이전트 ID를 stdout으로 출력 (tfx-route.sh에서 캡처)
+    console.log(JSON.stringify({ ok: true, agent_id: agentId, lease_expires_ms: result.data?.lease_expires_ms }));
+  } else {
+    // Hub 미실행 — 조용히 패스
+    console.log(JSON.stringify({ ok: false, reason: 'hub_unavailable' }));
+  }
+}
+
+async function cmdResult(args) {
+  const agentId = args.agent;
+  const filePath = args.file;
+  const topic = args.topic || 'task.result';
+  const traceId = args.trace || undefined;
+  const correlationId = args.correlation || undefined;
+  const exitCode = parseInt(args['exit-code'] || '0', 10);
+
+  // 결과 파일 읽기 (최대 48KB — Hub 메시지 크기 제한)
+  let output = '';
+  if (filePath && existsSync(filePath)) {
+    output = readFileSync(filePath, 'utf8').slice(0, 49152);
+  }
+
+  const result = await post('/bridge/result', {
+    agent_id: agentId,
+    topic,
+    payload: {
+      agent_id: agentId,
+      exit_code: exitCode,
+      output_length: output.length,
+      output_preview: output.slice(0, 4096), // 미리보기 4KB
+      output_file: filePath || null,
+      completed_at: Date.now(),
+    },
+    trace_id: traceId,
+    correlation_id: correlationId,
+  });
+
+  if (result?.ok) {
+    console.log(JSON.stringify({ ok: true, message_id: result.data?.message_id }));
+  } else {
+    console.log(JSON.stringify({ ok: false, reason: 'hub_unavailable' }));
+  }
+}
+
+async function cmdContext(args) {
+  const agentId = args.agent;
+  const topics = args.topics ? args.topics.split(',') : undefined;
+  const maxMessages = parseInt(args.max || '10', 10);
+  const outPath = args.out;
+
+  const result = await post('/bridge/context', {
+    agent_id: agentId,
+    topics,
+    max_messages: maxMessages,
+  });
+
+  if (result?.ok && result.data?.messages?.length) {
+    // 컨텍스트 조합
+    const parts = result.data.messages.map((m, i) => {
+      const from = m.from_agent || 'unknown';
+      const topic = m.topic || 'unknown';
+      const payload = typeof m.payload === 'string' ? m.payload : JSON.stringify(m.payload, null, 2);
+      return `=== Context ${i + 1}: ${from} (${topic}) ===\n${payload}`;
+    });
+    const combined = parts.join('\n\n');
+
+    if (outPath) {
+      writeFileSync(outPath, combined, 'utf8');
+      console.log(JSON.stringify({ ok: true, count: result.data.messages.length, file: outPath }));
+    } else {
+      console.log(combined);
+    }
+  } else {
+    if (outPath) {
+      console.log(JSON.stringify({ ok: true, count: 0 }));
+    }
+    // 메시지 없으면 빈 출력
+  }
+}
+
+async function cmdDeregister(args) {
+  const agentId = args.agent;
+  const result = await post('/bridge/deregister', { agent_id: agentId });
+
+  if (result?.ok) {
+    console.log(JSON.stringify({ ok: true, agent_id: agentId, status: 'offline' }));
+  } else {
+    console.log(JSON.stringify({ ok: false, reason: 'hub_unavailable' }));
+  }
+}
+
+async function cmdPing() {
+  try {
+    const url = `${_cachedHubUrl}/status`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 3000);
+    const res = await fetch(url, { signal: controller.signal });
+    clearTimeout(timer);
+    const data = await res.json();
+    console.log(JSON.stringify({ ok: true, hub: data.hub?.state, sessions: data.sessions }));
+  } catch {
+    console.log(JSON.stringify({ ok: false, reason: 'hub_unavailable' }));
+  }
+}
+
+// ── 메인 ──
+
+const cmd = process.argv[2];
+const args = parseArgs(process.argv.slice(3));
+
+switch (cmd) {
+  case 'register':   await cmdRegister(args); break;
+  case 'result':     await cmdResult(args); break;
+  case 'context':    await cmdContext(args); break;
+  case 'deregister': await cmdDeregister(args); break;
+  case 'ping':       await cmdPing(); break;
+  default:
+    console.error('사용법: bridge.mjs <register|result|context|deregister|ping> [--옵션]');
+    process.exit(1);
+}

package/hub/hitl.mjs

@@ -1,6 +1,5 @@
-// hub/hitl.mjs — Human-in-the-Loop 매니저
-// 사용자 입력 요청/응답, 타임아웃 자동 처리
-import { uuidv7 } from './store.mjs';
+// hub/hitl.mjs — Human-in-the-Loop 매니저
+// 사용자 입력 요청/응답, 타임아웃 자동 처리
 
 /**
  * HITL 매니저 생성
@@ -88,39 +87,36 @@ export function createHitlManager(store) {
      * 만료된 요청 자동 처리
      * 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;
-    },
+    checkTimeouts() {
+      const pending = store.getPendingHumanRequests();
+      const now = Date.now();
+      const expired = pending.filter(hr => hr.deadline_ms <= now);
+      if (!expired.length) return 0;
+
+      // 트랜잭션으로 만료 요청을 일괄 처리해 DB 왕복을 줄인다.
+      const processExpired = store.db.transaction(() => {
+        for (const hr of expired) {
+          store.updateHumanRequest(hr.request_id, 'timed_out', null);
+          if (hr.default_action === 'timeout_continue') {
+            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);
+          }
+        }
+        return expired.length;
+      });
+
+      return processExpired();
+    },
 
     /** 대기 중인 요청 목록 */
     getPendingRequests() {

package/hub/router.mjs

@@ -1,14 +1,17 @@
-// hub/router.mjs — Actor mailbox 라우터 + QoS 스케줄러
-// 메시지 라우팅, ask/publish/handoff 처리, TTL 정리
-import { uuidv7 } from './store.mjs';
+// hub/router.mjs — Actor mailbox 라우터 + QoS 스케줄러
+// 메시지 라우팅, ask/publish/handoff 처리, TTL 정리
+import { EventEmitter, once } from 'node:events';
+import { uuidv7 } from './store.mjs';
 
 /**
  * 라우터 생성
  * @param {object} store — createStore() 반환 객체
  */
-export function createRouter(store) {
-  let sweepTimer = null;
-  let staleTimer = null;
+export function createRouter(store) {
+  let sweepTimer = null;
+  let staleTimer = null;
+  const responseEmitter = new EventEmitter();
+  responseEmitter.setMaxListeners(200);
 
   const router = {
     /**
@@ -54,24 +57,29 @@ export function createRouter(store) {
         };
       }
 
-      // 짧은 폴링 대기 (최대 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' },
-      };
+      // 이벤트 기반 대기 (최대 30초 제한)
+      try {
+        const [payload] = await once(responseEmitter, cid, {
+          signal: AbortSignal.timeout(Math.min(await_response_ms, 30000)),
+        });
+        return {
+          ok: true,
+          data: { request_message_id: msg.id, correlation_id: cid, trace_id: tid, state: 'answered', response: payload },
+        };
+      } catch {
+        // 타임아웃 — DB에서 최종 확인
+        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 },
+          };
+        }
+        return {
+          ok: true,
+          data: { request_message_id: msg.id, correlation_id: cid, trace_id: tid, state: 'delivered' },
+        };
+      }
     },
 
     /**
@@ -83,16 +91,19 @@ export function createRouter(store) {
       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 },
-      };
+      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);
+      if (correlation_id) {
+        responseEmitter.emit(correlation_id, msg.payload);
+      }
+      return {
+        ok: true,
+        data: { message_id: msg.id, fanout_count: fanout, expires_at_ms: msg.expires_at_ms },
+      };
     },
 
     /**
@@ -118,15 +129,15 @@ export function createRouter(store) {
 
     // ── 스위퍼 ──
 
-    /** 주기적 만료 정리 시작 (1초: 메시지, 60초: 비활성 에이전트) */
-    startSweeper() {
-      if (sweepTimer) return;
-      sweepTimer = setInterval(() => {
-        try { store.sweepExpired(); } catch { /* 무시 */ }
-      }, 1000);
-      staleTimer = setInterval(() => {
-        try { store.sweepStaleAgents(); } catch { /* 무시 */ }
-      }, 60000);
+    /** 주기적 만료 정리 시작 (10초: 메시지, 60초: 비활성 에이전트) */
+    startSweeper() {
+      if (sweepTimer) return;
+      sweepTimer = setInterval(() => {
+        try { store.sweepExpired(); } catch { /* 무시 */ }
+      }, 10000);
+      staleTimer = setInterval(() => {
+        try { store.sweepStaleAgents(); } catch { /* 무시 */ }
+      }, 120000);
       sweepTimer.unref();
       staleTimer.unref();
     },
@@ -185,5 +196,5 @@ export function createRouter(store) {
     },
   };
 
-  return router;
-}
+  return { ...router, responseEmitter };
+}

package/hub/server.mjs

@@ -121,6 +121,87 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1' } = {}
       }));
     }
 
+    // /bridge/* — 경량 REST 엔드포인트 (tfx-route.sh 브릿지용)
+    if (req.url.startsWith('/bridge')) {
+      res.setHeader('Content-Type', 'application/json');
+
+      if (req.method !== 'POST' && req.method !== 'DELETE') {
+        res.writeHead(405);
+        return res.end(JSON.stringify({ ok: false, error: 'Method Not Allowed' }));
+      }
+
+      try {
+        const body = (req.method === 'POST') ? await parseBody(req) : {};
+        const path = req.url.replace(/\?.*/, '');
+
+        // POST /bridge/register — 에이전트 등록 (프로세스 수명 기반)
+        if (path === '/bridge/register' && req.method === 'POST') {
+          const { agent_id, cli, timeout_sec = 600, topics = [], capabilities = [], metadata = {} } = body;
+          if (!agent_id || !cli) {
+            res.writeHead(400);
+            return res.end(JSON.stringify({ ok: false, error: 'agent_id, cli 필수' }));
+          }
+          // heartbeat = 프로세스 타임아웃 + 여유 120초
+          const heartbeat_ttl_ms = (timeout_sec + 120) * 1000;
+          const data = store.registerAgent({ agent_id, cli, capabilities, topics, heartbeat_ttl_ms, metadata });
+          res.writeHead(200);
+          return res.end(JSON.stringify({ ok: true, data }));
+        }
+
+        // POST /bridge/result — 결과 발행
+        if (path === '/bridge/result' && req.method === 'POST') {
+          const { agent_id, topic = 'task.result', payload = {}, trace_id, correlation_id } = body;
+          if (!agent_id) {
+            res.writeHead(400);
+            return res.end(JSON.stringify({ ok: false, error: 'agent_id 필수' }));
+          }
+          const result = router.handlePublish({
+            from: agent_id, to: 'topic:' + topic, topic, payload,
+            priority: 5, ttl_ms: 3600000, trace_id, correlation_id,
+          });
+          res.writeHead(200);
+          return res.end(JSON.stringify(result));
+        }
+
+        // POST /bridge/context — 선행 컨텍스트 폴링
+        if (path === '/bridge/context' && req.method === 'POST') {
+          const { agent_id, topics, max_messages = 10 } = body;
+          if (!agent_id) {
+            res.writeHead(400);
+            return res.end(JSON.stringify({ ok: false, error: 'agent_id 필수' }));
+          }
+          const messages = store.pollForAgent(agent_id, {
+            max_messages,
+            include_topics: topics,
+            auto_ack: true,
+          });
+          res.writeHead(200);
+          return res.end(JSON.stringify({ ok: true, data: { messages, count: messages.length } }));
+        }
+
+        // POST /bridge/deregister — 에이전트 해제
+        if (path === '/bridge/deregister' && req.method === 'POST') {
+          const { agent_id } = body;
+          if (!agent_id) {
+            res.writeHead(400);
+            return res.end(JSON.stringify({ ok: false, error: 'agent_id 필수' }));
+          }
+          store.db.prepare("UPDATE agents SET status='offline' WHERE agent_id=?").run(agent_id);
+          res.writeHead(200);
+          return res.end(JSON.stringify({ ok: true, data: { agent_id, status: 'offline' } }));
+        }
+
+        res.writeHead(404);
+        return res.end(JSON.stringify({ ok: false, error: 'Unknown bridge endpoint' }));
+      } catch (e) {
+        if (!res.headersSent) {
+          res.writeHead(500);
+          res.end(JSON.stringify({ ok: false, error: e.message }));
+        }
+        return;
+      }
+    }
+
     // /mcp — MCP Streamable HTTP 엔드포인트
     if (req.url !== '/mcp') {
       res.writeHead(404);
@@ -133,18 +214,23 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1' } = {}
       if (req.method === 'POST') {
         const body = await parseBody(req);
 
-        if (sessionId && transports.has(sessionId)) {
-          // 기존 세션
-          await transports.get(sessionId).handleRequest(req, res, body);
-        } else if (!sessionId && isInitializeRequest(body)) {
-          // 새 세션 초기화
-          const transport = new StreamableHTTPServerTransport({
-            sessionIdGenerator: () => randomUUID(),
-            onsessioninitialized: (sid) => { transports.set(sid, transport); },
-          });
-          transport.onclose = () => {
-            if (transport.sessionId) transports.delete(transport.sessionId);
-          };
+        if (sessionId && transports.has(sessionId)) {
+          // 기존 세션
+          const t = transports.get(sessionId);
+          t._lastActivity = Date.now();
+          await t.handleRequest(req, res, body);
+        } else if (!sessionId && isInitializeRequest(body)) {
+          // 새 세션 초기화
+          const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            onsessioninitialized: (sid) => {
+              transport._lastActivity = Date.now();
+              transports.set(sid, transport);
+            },
+          });
+          transport.onclose = () => {
+            if (transport.sessionId) transports.delete(transport.sessionId);
+          };
           const mcp = createMcpForSession();
           await mcp.connect(transport);
           await transport.handleRequest(req, res, body);
@@ -202,17 +288,18 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1' } = {}
   }, 10000);
   hitlTimer.unref();
 
-  // stale 세션 정리 (60초 주기 — transport.onclose 미호출 대비)
-  const sessionTimer = setInterval(() => {
-    for (const [sid, transport] of transports) {
-      try {
-        if (transport._writableState?.destroyed || transport._readableState?.destroyed) {
-          transports.delete(sid);
-        }
-      } catch { transports.delete(sid); }
-    }
-  }, 60000);
-  sessionTimer.unref();
+  // 비활성 세션 정리 (60초 주기, 30분 TTL)
+  const SESSION_TTL_MS = 30 * 60 * 1000;
+  const sessionTimer = setInterval(() => {
+    const now = Date.now();
+    for (const [sid, transport] of transports) {
+      if (now - (transport._lastActivity || 0) > SESSION_TTL_MS) {
+        try { transport.close(); } catch {}
+        transports.delete(sid);
+      }
+    }
+  }, 60000);
+  sessionTimer.unref();
 
   // PID 파일 기록
   mkdirSync(PID_DIR, { recursive: true });

package/hub/store.mjs

@@ -6,12 +6,23 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { randomBytes } from 'node:crypto';
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-/** UUIDv7 생성 (RFC 9562) */
-export function uuidv7() {
-  const now = BigInt(Date.now());
-  const buf = randomBytes(16);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+let _rndPool = Buffer.alloc(0), _rndOff = 0;
+
+function pooledRandom(n) {
+  if (_rndOff + n > _rndPool.length) {
+    _rndPool = randomBytes(256);
+    _rndOff = 0;
+  }
+  const out = Buffer.from(_rndPool.subarray(_rndOff, _rndOff + n));
+  _rndOff += n;
+  return out;
+}
+
+/** UUIDv7 생성 (RFC 9562) */
+export function uuidv7() {
+  const now = BigInt(Date.now());
+  const buf = pooledRandom(16);
   buf[0] = Number((now >> 40n) & 0xffn);
   buf[1] = Number((now >> 32n) & 0xffn);
   buf[2] = Number((now >> 24n) & 0xffn);
@@ -62,9 +73,20 @@ export function createStore(dbPath) {
   db.pragma('busy_timeout = 5000');
   db.pragma('wal_autocheckpoint = 1000');
 
-  // 스키마 초기화 (schema.sql 전체 실행 — 주석 포함 안전 처리)
-  const schemaSQL = readFileSync(join(__dirname, 'schema.sql'), 'utf8');
-  db.exec(schemaSQL);
+  // 스키마 초기화 (schema.sql 전체 실행 — 주석 포함 안전 처리)
+  const schemaSQL = readFileSync(join(__dirname, 'schema.sql'), 'utf8');
+
+  // 스키마 버전 체크 — 불필요한 재실행 방지
+  db.exec("CREATE TABLE IF NOT EXISTS _meta (key TEXT PRIMARY KEY, value TEXT)");
+  const SCHEMA_VERSION = '1';
+  const curVer = (() => {
+    try { return db.prepare("SELECT value FROM _meta WHERE key='schema_version'").pluck().get(); }
+    catch { return null; }
+  })();
+  if (curVer !== SCHEMA_VERSION) {
+    db.exec(schemaSQL);
+    db.prepare("INSERT OR REPLACE INTO _meta (key, value) VALUES ('schema_version', ?)").run(SCHEMA_VERSION);
+  }
 
   // ── 준비된 구문 ──
 
@@ -84,7 +106,7 @@ export function createStore(dbPath) {
     allAgents: db.prepare('SELECT * FROM agents'),
     agentsByTopic: db.prepare("SELECT a.* FROM agents a, json_each(a.topics_json) t WHERE t.value=? AND a.status != 'offline'"),
     markStale: db.prepare("UPDATE agents SET status='stale' WHERE status='online' AND lease_expires_ms < ?"),
-    markOffline: db.prepare("UPDATE agents SET status='offline' WHERE status='stale' AND lease_expires_ms < ? - 60000"),
+    markOffline: db.prepare("UPDATE agents SET status='offline' WHERE status='stale' AND lease_expires_ms < ? - 300000"),
 
     // 메시지
     insertMsg: db.prepare(`

package/hub/tools.mjs

@@ -38,7 +38,7 @@ export function createTools(store, router, hitl) {
           capabilities:     { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: 64 },
           topics:           { type: 'array', items: { type: 'string' }, maxItems: 64 },
           metadata:         { type: 'object' },
-          heartbeat_ttl_ms: { type: 'integer', minimum: 5000, maximum: 300000 },
+          heartbeat_ttl_ms: { type: 'integer', minimum: 10000, maximum: 7200000 },
         },
       },
       handler: wrap('REGISTER_FAILED', (args) => {
@@ -145,15 +145,19 @@ export function createTools(store, router, hitl) {
           auto_ack: args.auto_ack,
         });
 
-        // wait_ms > 0 이고 메시지 없으면 대기 후 재시도
-        if (!messages.length && args.wait_ms > 0) {
-          await new Promise(r => setTimeout(r, Math.min(args.wait_ms, 30000)));
-          messages = store.pollForAgent(args.agent_id, {
-            max_messages: args.max_messages,
-            include_topics: args.include_topics,
-            auto_ack: args.auto_ack,
-          });
-        }
+        // wait_ms > 0 이고 메시지 없으면 짧은 간격으로 반복 재시도
+        if (!messages.length && args.wait_ms > 0) {
+          const interval = Math.min(args.wait_ms, 500);
+          const deadline = Date.now() + Math.min(args.wait_ms, 30000);
+          while (!messages.length && Date.now() < deadline) {
+            await new Promise(r => setTimeout(r, interval));
+            messages = store.pollForAgent(args.agent_id, {
+              max_messages: args.max_messages,
+              include_topics: args.include_topics,
+              auto_ack: args.auto_ack,
+            });
+          }
+        }
 
         return {
           ok: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "3.1.0-dev.2",
+  "version": "3.1.0-dev.4",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {

package/scripts/setup.mjs

@@ -130,6 +130,19 @@ if (existsSync(hudPath)) {
   }
 }
 
+// ── Stale PID 파일 정리 (hub 좀비 방지) ──
+
+const HUB_PID_FILE = join(CLAUDE_DIR, "cache", "tfx-hub", "hub.pid");
+if (existsSync(HUB_PID_FILE)) {
+  try {
+    const pidInfo = JSON.parse(readFileSync(HUB_PID_FILE, "utf8"));
+    process.kill(pidInfo.pid, 0); // 프로세스 존재 확인 (신호 미전송)
+  } catch {
+    try { unlinkSync(HUB_PID_FILE); } catch {} // 죽은 프로세스면 PID 파일 삭제
+    synced++;
+  }
+}
+
 // ── HUD 에러 캐시 자동 클리어 (업데이트/재설치 시) ──
 
 const cacheDir = join(CLAUDE_DIR, "cache");

package/scripts/tfx-route.sh

@@ -38,6 +38,38 @@ STDERR_LOG="/tmp/tfx-route-${AGENT_TYPE}-${TIMESTAMP}-stderr.log"
 STDOUT_LOG="/tmp/tfx-route-${AGENT_TYPE}-${TIMESTAMP}-stdout.log"
 TFX_TMP="${TMPDIR:-/tmp}"
 
+# ── Hub 브릿지 (선택적 — Hub 미실행 시 무시) ──
+# 패키지 내 브릿지 탐색 (npm global / git local 모두 대응)
+find_bridge() {
+  # 1. 환경변수 지정
+  [[ -n "${TFX_BRIDGE:-}" && -f "$TFX_BRIDGE" ]] && echo "$TFX_BRIDGE" && return
+  # 2. 같은 패키지 내
+  local script_dir
+  script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  local pkg_bridge="${script_dir}/../hub/bridge.mjs"
+  [[ -f "$pkg_bridge" ]] && echo "$pkg_bridge" && return
+  # 3. 설치된 triflux 패키지
+  local npm_bridge
+  npm_bridge="$(npm root -g 2>/dev/null)/triflux/hub/bridge.mjs"
+  [[ -f "$npm_bridge" ]] && echo "$npm_bridge" && return
+  echo ""
+}
+BRIDGE_BIN="$(find_bridge)"
+HUB_ENABLED="false"
+if [[ -n "$BRIDGE_BIN" ]]; then
+  # Hub 핑 (3초 타임아웃, 실패 시 무시)
+  HUB_PING=$(node "$BRIDGE_BIN" ping 2>/dev/null || echo '{"ok":false}')
+  if echo "$HUB_PING" | grep -q '"ok":true'; then
+    HUB_ENABLED="true"
+  fi
+fi
+
+# Hub 브릿지 래퍼 (Hub 꺼져있으면 아무것도 안 함)
+hub_bridge() {
+  [[ "$HUB_ENABLED" != "true" ]] && return 0
+  node "$BRIDGE_BIN" "$@" 2>/dev/null || true
+}
+
 # fallback 시 원래 에이전트 정보 보존
 ORIGINAL_AGENT=""
 ORIGINAL_CLI_ARGS=""
@@ -353,11 +385,31 @@ ${ctx_content}
 
   # 메타정보 (stderr)
   echo "[tfx-route] v${VERSION} type=$CLI_TYPE agent=$AGENT_TYPE effort=$CLI_EFFORT mode=$RUN_MODE timeout=${TIMEOUT_SEC}s" >&2
-  echo "[tfx-route] opus_oversight=$OPUS_OVERSIGHT mcp_profile=$MCP_PROFILE" >&2
+  echo "[tfx-route] opus_oversight=$OPUS_OVERSIGHT mcp_profile=$MCP_PROFILE hub=$HUB_ENABLED" >&2
 
   # Per-process 에이전트 등록
   register_agent
 
+  # Hub 브릿지: 에이전트 등록 (프로세스 수명 기반 lease)
+  local hub_agent_id="${AGENT_TYPE}-$$"
+  local hub_topics="${AGENT_TYPE},task.result"
+  hub_bridge register \
+    --agent "$hub_agent_id" \
+    --cli "$CLI_TYPE" \
+    --timeout "$TIMEOUT_SEC" \
+    --topics "$hub_topics" \
+    --capabilities "code,${AGENT_TYPE}"
+
+  # Hub 브릿지: 선행 컨텍스트 폴링 (DAG 의존 태스크용)
+  if [[ "$HUB_ENABLED" == "true" && -z "$CONTEXT_FILE" ]]; then
+    local hub_ctx_file="${TFX_TMP}/tfx-hub-ctx-${hub_agent_id}.md"
+    hub_bridge context --agent "$hub_agent_id" --topics "$hub_topics" --out "$hub_ctx_file"
+    if [[ -s "$hub_ctx_file" ]]; then
+      CONTEXT_FILE="$hub_ctx_file"
+      echo "[tfx-route] hub: 선행 컨텍스트 수신 ($(wc -c < "$hub_ctx_file") bytes)" >&2
+    fi
+  fi
+
   # CLI 실행 (stderr 분리 + 타임아웃 + 소요시간 측정)
   local exit_code=0
   local start_time
@@ -414,6 +466,14 @@ ${ctx_content}
   end_time=$(date +%s)
   local elapsed=$((end_time - start_time))
 
+  # Hub 브릿지: 결과 발행 + 에이전트 해제
+  hub_bridge result \
+    --agent "$hub_agent_id" \
+    --file "$STDOUT_LOG" \
+    --topic "task.result" \
+    --exit-code "$exit_code"
+  hub_bridge deregister --agent "$hub_agent_id"
+
   # ── 후처리: 단일 node 프로세스로 위임 ──
   # 토큰 추출, 출력 필터링, 로그, 토큰 누적, AIMD, 이슈 추적, 결과 출력 전부 처리
   local post_script="${HOME}/.claude/scripts/tfx-route-post.mjs"

package/skills/tfx-hub/SKILL.md

@@ -1,15 +1,43 @@
-# tfx-hub — MCP 메시지 버스 관리
+---
+name: tfx-hub
+description: tfx-hub 개방형 스킬 — 커맨드(start/stop/status) + 자유형 작업 모두 처리
+triggers:
+  - tfx-hub
+argument-hint: "<start|stop|status|자유형 작업 설명>"
+---
+
+# tfx-hub — MCP 메시지 버스 관리 + 개방형 작업
 
 > CLI 에이전트(Codex/Gemini/Claude) 간 실시간 메시지 허브를 관리합니다.
-> **tfx-auto와 완전 독립** — 별도 스킬로 운영됩니다.
+> **커맨드 매칭 + fallthrough**: start/stop/status에 매칭되면 즉시 실행,
+> 매칭 안 되면 **hub 도메인 컨텍스트를 활용한 범용 작업**으로 처리합니다.
 
-## 사용법
+## 입력 해석 규칙
 
 ```
-/tfx-hub start               ← 허브 데몬 시작 (기본 포트 27888)
-/tfx-hub start --port 28000  ← 커스텀 포트
-/tfx-hub stop                ← 허브 중지
-/tfx-hub status              ← 상태/메트릭 확인
+/tfx-hub start          → 커맨드 매칭 → 허브 시작
+/tfx-hub stop           → 커맨드 매칭 → 허브 중지
+/tfx-hub status         → 커맨드 매칭 → 상태 확인
+/tfx-hub 테스트해줘      → fallthrough → hub 관련 범용 작업으로 처리
+/tfx-hub 문서 저장해     → fallthrough → hub 관련 범용 작업으로 처리
+/tfx-hub 브릿지 분석해   → fallthrough → hub 관련 범용 작업으로 처리
+```
+
+**fallthrough 규칙**: 인자가 start/stop/status/--port 등 커맨드 키워드에 매칭되지 않으면,
+사용자의 입력을 **hub/브릿지/메시지버스 도메인의 자유형 작업**으로 해석한다.
+
+fallthrough 라우팅:
+```bash
+# tfx-route.sh 경유 (권장)
+Bash("bash ~/.claude/scripts/tfx-route.sh {에이전트} '{hub 컨텍스트 + 작업}' {mcp_profile}")
+
+# codex 직접 호출 시 — 반드시 exec 서브커맨드 포함
+Bash("codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check '{작업}'")
+Bash("codex --profile xhigh exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check '{작업}'")
+#          ↑ --profile은 exec 앞에, --skip-git-repo-check은 exec 뒤에
+
+# Claude 네이티브 (탐색/검증)
+Agent(subagent_type="oh-my-claudecode:explore", prompt="{작업}")
 ```
 
 ## 커맨드
@@ -78,6 +106,28 @@ claude mcp add --transport http tfx-hub http://127.0.0.1:27888/mcp
 | `request_human_input` | 사용자 입력 요청 (CAPTCHA/승인) |
 | `submit_human_input` | 사용자 입력 응답 |
 
+## 브릿지 REST 엔드포인트 (4개)
+
+| 엔드포인트 | 설명 |
+|-----------|------|
+| `POST /bridge/register` | 에이전트 등록 (프로세스 수명 기반 lease) |
+| `POST /bridge/result` | 결과 발행 (topic fanout) |
+| `POST /bridge/context` | 선행 컨텍스트 폴링 (auto_ack) |
+| `POST /bridge/deregister` | 에이전트 offline 마킹 |
+
+## 프로젝트 구조
+
+```
+hub/
+├── server.mjs    # MCP 서버 + REST 브릿지 엔드포인트
+├── store.mjs     # SQLite WAL 상태 저장소
+├── router.mjs    # Actor mailbox 라우터 + QoS
+├── tools.mjs     # MCP 도구 8개 정의
+├── hitl.mjs      # Human-in-the-Loop 매니저
+├── bridge.mjs    # tfx-route.sh ↔ hub 브릿지 CLI
+└── schema.sql    # DB 스키마
+```
+
 ## 상태
 
 **dev 전용** — 로컬 테스트 목적. 프로덕션 배포 전 안정화 필요.