triflux 3.1.0-dev.3 → 3.1.0-dev.4

package/hub/bridge.mjs

@@ -14,15 +14,16 @@
 // Hub 미실행 시 모든 커맨드는 조용히 실패 (exit 0).
 // tfx-route.sh 흐름을 절대 차단하지 않는다.
 
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { homedir } from 'node:os';
+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() {
+function getHubUrl() {
   // 환경변수 우선
   if (process.env.TFX_HUB_URL) return process.env.TFX_HUB_URL.replace(/\/mcp$/, '');
 
@@ -35,16 +36,18 @@ function getHubUrl() {
   }
 
   // 기본값
-  const port = process.env.TFX_HUB_PORT || '27888';
-  return `http://127.0.0.1:${port}`;
-}
-
-// ── HTTP 요청 ──
-
-async function post(path, body, timeoutMs = 5000) {
-  const url = `${getHubUrl()}${path}`;
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  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, {
@@ -63,22 +66,27 @@ async function post(path, body, timeoutMs = 5000) {
 
 // ── 인자 파싱 ──
 
-function parseArgs(argv) {
-  const args = {};
-  for (let i = 0; i < argv.length; i++) {
-    if (argv[i].startsWith('--')) {
-      const key = argv[i].slice(2);
-      const next = argv[i + 1];
-      if (!next || next.startsWith('--')) {
-        args[key] = true;
-      } else {
-        args[key] = next;
-        i++;
-      }
-    }
-  }
-  return args;
-}
+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;
+}
 
 // ── 커맨드 ──
 
@@ -127,14 +135,14 @@ async function cmdResult(args) {
   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_full: output, // 전체 (최대 48KB)
-      completed_at: Date.now(),
-    },
+    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,
   });
@@ -193,10 +201,10 @@ async function cmdDeregister(args) {
   }
 }
 
-async function cmdPing() {
-  try {
-    const url = `${getHubUrl()}/status`;
-    const controller = new AbortController();
+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);

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 { /* 무시 */ }
-      }, 120000);
+    /** 주기적 만료 정리 시작 (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

@@ -214,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);
@@ -283,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);
+  }
 
   // ── 준비된 구문 ──
 

package/hub/tools.mjs

@@ -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.3",
+  "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/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 전용** — 로컬 테스트 목적. 프로덕션 배포 전 안정화 필요.