triflux 3.0.0 → 3.1.0-dev.2

package/hub/tools.mjs

@@ -0,0 +1,238 @@
+// hub/tools.mjs — MCP 도구 8개 정의
+// register, status, publish, ask, poll_messages, handoff, request_human_input, submit_human_input
+// 모든 도구 응답: { ok: boolean, error?: { code, message }, data?: ... }
+
+/**
+ * MCP 도구 목록 생성
+ * @param {object} store  — createStore() 반환
+ * @param {object} router — createRouter() 반환
+ * @param {object} hitl   — createHitlManager() 반환
+ * @returns {Array<{name, description, inputSchema, handler}>}
+ */
+export function createTools(store, router, hitl) {
+  /** 도구 핸들러 래퍼 — 에러 처리 + MCP content 형식 변환 */
+  function wrap(code, fn) {
+    return async (args) => {
+      try {
+        const result = await fn(args);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+      } catch (e) {
+        const err = { ok: false, error: { code, message: e.message } };
+        return { content: [{ type: 'text', text: JSON.stringify(err) }], isError: true };
+      }
+    };
+  }
+
+  return [
+    // ── 1. register ──
+    {
+      name: 'register',
+      description: '에이전트를 허브에 등록하고 lease를 발급받습니다',
+      inputSchema: {
+        type: 'object',
+        required: ['agent_id', 'cli', 'capabilities', 'topics', 'heartbeat_ttl_ms'],
+        properties: {
+          agent_id:         { type: 'string', pattern: '^[a-zA-Z0-9._:-]{3,64}$' },
+          cli:              { type: 'string', enum: ['codex', 'gemini', 'claude', 'other'] },
+          pid:              { type: 'integer', minimum: 1 },
+          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 },
+        },
+      },
+      handler: wrap('REGISTER_FAILED', (args) => {
+        const data = store.registerAgent(args);
+        return { ok: true, data };
+      }),
+    },
+
+    // ── 2. status ──
+    {
+      name: 'status',
+      description: '허브, 에이전트, 큐, 트레이스 상태를 조회합니다',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          scope:           { type: 'string', enum: ['hub', 'agent', 'queue', 'trace'], default: 'hub' },
+          agent_id:        { type: 'string' },
+          trace_id:        { type: 'string' },
+          include_metrics: { type: 'boolean', default: true },
+        },
+      },
+      handler: wrap('STATUS_FAILED', (args) => {
+        return router.getStatus(args.scope || 'hub', args);
+      }),
+    },
+
+    // ── 3. publish ──
+    {
+      name: 'publish',
+      description: '이벤트 또는 응답 메시지를 발행합니다. to에 "topic:XXX" 지정 시 구독자 전체 fanout',
+      inputSchema: {
+        type: 'object',
+        required: ['from', 'to', 'topic', 'payload'],
+        properties: {
+          from:           { type: 'string', pattern: '^[a-zA-Z0-9._:-]{3,64}$' },
+          to:             { type: 'string' },
+          topic:          { type: 'string', pattern: '^[a-zA-Z0-9._:-]+$' },
+          priority:       { type: 'integer', minimum: 1, maximum: 9, default: 5 },
+          ttl_ms:         { type: 'integer', minimum: 1000, maximum: 86400000, default: 300000 },
+          payload:        { type: 'object' },
+          trace_id:       { type: 'string' },
+          correlation_id: { type: 'string' },
+        },
+      },
+      handler: wrap('PUBLISH_FAILED', (args) => {
+        return router.handlePublish(args);
+      }),
+    },
+
+    // ── 4. ask ──
+    {
+      name: 'ask',
+      description: '다른 에이전트에게 질문합니다. await_response_ms > 0이면 짧은 폴링으로 응답 대기',
+      inputSchema: {
+        type: 'object',
+        required: ['from', 'to', 'topic', 'question'],
+        properties: {
+          from:              { type: 'string', pattern: '^[a-zA-Z0-9._:-]{3,64}$' },
+          to:                { type: 'string' },
+          topic:             { type: 'string', pattern: '^[a-zA-Z0-9._:-]+$' },
+          question:          { type: 'string', minLength: 1, maxLength: 20000 },
+          context_refs:      { type: 'array', items: { type: 'string' }, maxItems: 32 },
+          payload:           { type: 'object' },
+          priority:          { type: 'integer', minimum: 1, maximum: 9, default: 5 },
+          ttl_ms:            { type: 'integer', minimum: 1000, maximum: 86400000, default: 300000 },
+          await_response_ms: { type: 'integer', minimum: 0, maximum: 30000, default: 0 },
+          trace_id:          { type: 'string' },
+          correlation_id:    { type: 'string' },
+        },
+      },
+      handler: wrap('ASK_FAILED', async (args) => {
+        return await router.handleAsk(args);
+      }),
+    },
+
+    // ── 5. poll_messages ──
+    {
+      name: 'poll_messages',
+      description: '에이전트 수신함에서 대기 메시지를 가져옵니다. ack_ids로 이전 메시지 확인 가능',
+      inputSchema: {
+        type: 'object',
+        required: ['agent_id'],
+        properties: {
+          agent_id:       { type: 'string', pattern: '^[a-zA-Z0-9._:-]{3,64}$' },
+          wait_ms:        { type: 'integer', minimum: 0, maximum: 30000, default: 1000 },
+          max_messages:   { type: 'integer', minimum: 1, maximum: 100, default: 20 },
+          include_topics: { type: 'array', items: { type: 'string' }, maxItems: 64 },
+          ack_ids:        { type: 'array', items: { type: 'string' }, maxItems: 100 },
+          auto_ack:       { type: 'boolean', default: false },
+        },
+      },
+      handler: wrap('POLL_FAILED', async (args) => {
+        // ACK 먼저 처리
+        const ackedIds = [];
+        if (args.ack_ids?.length) {
+          store.ackMessages(args.ack_ids, args.agent_id);
+          ackedIds.push(...args.ack_ids);
+        }
+
+        // 1차 폴링
+        let 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) {
+          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,
+          });
+        }
+
+        return {
+          ok: true,
+          data: {
+            messages,
+            acked_ids: ackedIds,
+            next_poll_after_ms: messages.length ? 0 : 1000,
+            server_time_ms: Date.now(),
+          },
+        };
+      }),
+    },
+
+    // ── 6. handoff ──
+    {
+      name: 'handoff',
+      description: '다른 에이전트에게 작업을 인계합니다. acceptance_criteria로 완료 기준 지정 가능',
+      inputSchema: {
+        type: 'object',
+        required: ['from', 'to', 'topic', 'task'],
+        properties: {
+          from:                { type: 'string', pattern: '^[a-zA-Z0-9._:-]{3,64}$' },
+          to:                  { type: 'string' },
+          topic:               { type: 'string', pattern: '^[a-zA-Z0-9._:-]+$' },
+          task:                { type: 'string', minLength: 1, maxLength: 20000 },
+          acceptance_criteria: { type: 'array', items: { type: 'string' }, maxItems: 32 },
+          context_refs:        { type: 'array', items: { type: 'string' }, maxItems: 32 },
+          priority:            { type: 'integer', minimum: 1, maximum: 9, default: 5 },
+          ttl_ms:              { type: 'integer', minimum: 1000, maximum: 86400000, default: 600000 },
+          trace_id:            { type: 'string' },
+          correlation_id:      { type: 'string' },
+        },
+      },
+      handler: wrap('HANDOFF_FAILED', (args) => {
+        return router.handleHandoff(args);
+      }),
+    },
+
+    // ── 7. request_human_input ──
+    {
+      name: 'request_human_input',
+      description: '사용자에게 입력을 요청합니다 (CAPTCHA, 승인, 자격증명, 선택, 텍스트)',
+      inputSchema: {
+        type: 'object',
+        required: ['requester_agent', 'kind', 'prompt', 'requested_schema', 'deadline_ms', 'default_action'],
+        properties: {
+          requester_agent:    { type: 'string', pattern: '^[a-zA-Z0-9._:-]{3,64}$' },
+          kind:               { type: 'string', enum: ['captcha', 'approval', 'credential', 'choice', 'text'] },
+          prompt:             { type: 'string', minLength: 1, maxLength: 20000 },
+          requested_schema:   { type: 'object' },
+          deadline_ms:        { type: 'integer', minimum: 1000 },
+          default_action:     { type: 'string', enum: ['decline', 'cancel', 'timeout_continue'] },
+          channel_preference: { type: 'string', enum: ['terminal', 'pipe', 'file_polling'], default: 'terminal' },
+          trace_id:           { type: 'string' },
+          correlation_id:     { type: 'string' },
+        },
+      },
+      handler: wrap('HITL_REQUEST_FAILED', (args) => {
+        return hitl.requestHumanInput(args);
+      }),
+    },
+
+    // ── 8. submit_human_input ──
+    {
+      name: 'submit_human_input',
+      description: '사용자 입력 요청에 응답합니다 (accept, decline, cancel)',
+      inputSchema: {
+        type: 'object',
+        required: ['request_id', 'action'],
+        properties: {
+          request_id:   { type: 'string' },
+          action:       { type: 'string', enum: ['accept', 'decline', 'cancel'] },
+          content:      { type: 'object' },
+          submitted_by: { type: 'string', default: 'human' },
+        },
+      },
+      handler: wrap('HITL_SUBMIT_FAILED', (args) => {
+        return hitl.submitHumanInput(args);
+      }),
+    },
+  ];
+}

package/hud/hud-qos-status.mjs

@@ -660,14 +660,17 @@ function fetchClaudeUsageFromApi(accessToken) {
 }
 
 function parseClaudeUsageResponse(response) {
-  const fiveHour = response?.five_hour?.utilization;
-  const sevenDay = response?.seven_day?.utilization;
-  if (fiveHour == null && sevenDay == null) return null;
+  if (!response || typeof response !== "object") return null;
+  // five_hour/seven_day 키 자체가 없으면 비정상 응답
+  if (!response.five_hour && !response.seven_day) return null;
+  const fiveHour = response.five_hour?.utilization;
+  const sevenDay = response.seven_day?.utilization;
+  // utilization이 null이면 0%로 처리 (API 200 성공 시 null = 사용량 없음)
   return {
     fiveHourPercent: clampPercent(fiveHour ?? 0),
     weeklyPercent: clampPercent(sevenDay ?? 0),
-    fiveHourResetsAt: response?.five_hour?.resets_at || null,
-    weeklyResetsAt: response?.seven_day?.resets_at || null,
+    fiveHourResetsAt: response.five_hour?.resets_at || null,
+    weeklyResetsAt: response.seven_day?.resets_at || null,
   };
 }
 
@@ -693,6 +696,13 @@ function readClaudeUsageSnapshot() {
 
   // 1차: 자체 캐시에 유효 데이터가 있는 경우
   if (cache?.data) {
+    // 에러 상태에서 보존된 stale 데이터 → backoff 존중하되 표시용 데이터 반환
+    if (cache.error) {
+      const backoffMs = cache.errorType === "rate_limit"
+        ? CLAUDE_USAGE_429_BACKOFF_MS
+        : CLAUDE_USAGE_ERROR_BACKOFF_MS;
+      return { data: stripStaleResets(cache.data), shouldRefresh: ageMs >= backoffMs };
+    }
     const isFresh = ageMs < getClaudeUsageStaleMs();
     return { data: cache.data, shouldRefresh: !isFresh };
   }
@@ -733,13 +743,22 @@ function readClaudeUsageSnapshot() {
 }
 
 function writeClaudeUsageCache(data, errorInfo = null) {
-  writeJsonSafe(CLAUDE_USAGE_CACHE_PATH, {
+  const entry = {
     timestamp: Date.now(),
     data,
     error: !!errorInfo,
     errorType: errorInfo?.type || null,   // "rate_limit" | "auth" | "network" | "unknown"
     errorStatus: errorInfo?.status || null, // HTTP 상태 코드
-  });
+  };
+  // 에러 시 기존 유효 데이터 보존 (--% n/a 방지)
+  if (errorInfo && data == null) {
+    const prev = readJson(CLAUDE_USAGE_CACHE_PATH, null);
+    if (prev?.data) {
+      entry.data = prev.data;
+      entry.stale = true;
+    }
+  }
+  writeJsonSafe(CLAUDE_USAGE_CACHE_PATH, entry);
 }
 
 async function fetchClaudeUsage(forceRefresh = false) {

package/package.json

@@ -1,51 +1,56 @@
-{
-  "name": "triflux",
-  "version": "3.0.0",
-  "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
-  "type": "module",
-  "bin": {
-    "triflux": "bin/triflux.mjs",
-    "tfx": "bin/triflux.mjs",
-    "tfl": "bin/triflux.mjs",
-    "tfx-setup": "bin/tfx-setup.mjs",
-    "tfx-doctor": "bin/tfx-doctor.mjs"
-  },
-  "files": [
-    "bin",
-    "skills",
-    "!**/failure-reports",
-    "scripts",
-    "hooks",
-    "hud",
-    ".claude-plugin",
-    ".mcp.json",
-    "README.md",
-    "README.ko.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "setup": "node scripts/setup.mjs",
-    "postinstall": "node scripts/setup.mjs"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/tellang/triflux.git"
-  },
-  "homepage": "https://github.com/tellang/triflux#readme",
-  "author": "tellang",
-  "license": "MIT",
-  "keywords": [
-    "claude-code",
-    "plugin",
-    "codex",
-    "gemini",
-    "cli-routing",
-    "orchestration",
-    "multi-model",
-    "triflux",
-    "tfx"
-  ]
-}
+{
+  "name": "triflux",
+  "version": "3.1.0-dev.2",
+  "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
+  "type": "module",
+  "bin": {
+    "triflux": "bin/triflux.mjs",
+    "tfx": "bin/triflux.mjs",
+    "tfl": "bin/triflux.mjs",
+    "tfx-setup": "bin/tfx-setup.mjs",
+    "tfx-doctor": "bin/tfx-doctor.mjs"
+  },
+  "files": [
+    "bin",
+    "hub",
+    "skills",
+    "!**/failure-reports",
+    "scripts",
+    "hooks",
+    "hud",
+    ".claude-plugin",
+    ".mcp.json",
+    "README.md",
+    "README.ko.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "setup": "node scripts/setup.mjs",
+    "postinstall": "node scripts/setup.mjs"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tellang/triflux.git"
+  },
+  "homepage": "https://github.com/tellang/triflux#readme",
+  "author": "tellang",
+  "license": "MIT",
+  "dependencies": {
+    "better-sqlite3": "^12.6.2",
+    "@modelcontextprotocol/sdk": "^1.27.1"
+  },
+  "keywords": [
+    "claude-code",
+    "plugin",
+    "codex",
+    "gemini",
+    "cli-routing",
+    "orchestration",
+    "multi-model",
+    "triflux",
+    "tfx"
+  ]
+}

package/skills/tfx-hub/SKILL.md

@@ -0,0 +1,83 @@
+# tfx-hub — MCP 메시지 버스 관리
+
+> CLI 에이전트(Codex/Gemini/Claude) 간 실시간 메시지 허브를 관리합니다.
+> **tfx-auto와 완전 독립** — 별도 스킬로 운영됩니다.
+
+## 사용법
+
+```
+/tfx-hub start               ← 허브 데몬 시작 (기본 포트 27888)
+/tfx-hub start --port 28000  ← 커스텀 포트
+/tfx-hub stop                ← 허브 중지
+/tfx-hub status              ← 상태/메트릭 확인
+```
+
+## 커맨드
+
+### start — 허브 시작
+
+```bash
+Bash("node hub/server.mjs", run_in_background=true)
+```
+
+- Streamable HTTP MCP 서버를 `http://127.0.0.1:27888/mcp` 에서 시작
+- SQLite WAL DB: `~/.claude/cache/tfx-hub/state.db`
+- PID 파일: `~/.claude/cache/tfx-hub/hub.pid`
+- 환경변수: `TFX_HUB_PORT` (포트), `TFX_HUB_DB` (DB 경로)
+
+### stop — 허브 중지
+
+```bash
+# PID 파일에서 프로세스 ID 읽어서 종료
+Bash("node -e \"
+  const fs = require('fs');
+  const path = require('path');
+  const pidFile = path.join(require('os').homedir(), '.claude/cache/tfx-hub/hub.pid');
+  if (fs.existsSync(pidFile)) {
+    const info = JSON.parse(fs.readFileSync(pidFile, 'utf8'));
+    process.kill(info.pid, 'SIGTERM');
+    console.log('tfx-hub 종료 (PID ' + info.pid + ')');
+  } else {
+    console.log('tfx-hub 미실행');
+  }
+\"")
+```
+
+### status — 상태 확인
+
+```bash
+# HTTP 상태 엔드포인트 조회
+Bash("curl -s http://127.0.0.1:27888/status 2>/dev/null || echo '{\"error\":\"hub 미실행\"}'")
+```
+
+## 각 CLI 등록 방법
+
+허브 시작 후 각 CLI에 MCP 서버로 등록:
+
+```bash
+# Codex
+codex mcp add tfx-hub --url http://127.0.0.1:27888/mcp
+
+# Gemini (settings.json)
+# mcpServers.tfx-hub.url = "http://127.0.0.1:27888/mcp"
+
+# Claude
+claude mcp add --transport http tfx-hub http://127.0.0.1:27888/mcp
+```
+
+## MCP 도구 (8개)
+
+| 도구 | 설명 |
+|------|------|
+| `register` | 에이전트 등록 + lease 발급 |
+| `status` | 허브/에이전트/큐 상태 조회 |
+| `publish` | 이벤트/응답 메시지 발행 |
+| `ask` | 다른 에이전트에게 질문 (request/reply) |
+| `poll_messages` | 수신함에서 메시지 폴링 |
+| `handoff` | 작업 인계 |
+| `request_human_input` | 사용자 입력 요청 (CAPTCHA/승인) |
+| `submit_human_input` | 사용자 입력 응답 |
+
+## 상태
+
+**dev 전용** — 로컬 테스트 목적. 프로덕션 배포 전 안정화 필요.