triflux 2.5.1 → 3.1.0-dev.1

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

@@ -509,7 +509,7 @@ function normalizeTimeToken(value) {
   }
   const dayHour = text.match(/^(\d+)d(\d+)h$/);
   if (dayHour) {
-    return `${Number(dayHour[1])}d${Number(dayHour[2])}h`;
+    return `${Number(dayHour[1])}d${String(Number(dayHour[2])).padStart(2, "0")}h`;
   }
   return text;
 }
@@ -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) {
@@ -958,7 +977,9 @@ function getGeminiEmail() {
 // ============================================================================
 function getCodexRateLimits() {
   const now = new Date();
-  let todayHasFiles = false;
+  let syntheticBucket = null; // 오늘 token_count에서 합성 (행 활성화 + 토큰 데이터용)
+
+  // 2일간 스캔: 실제 rate_limits 우선, 합성 버킷은 폴백
   for (let dayOffset = 0; dayOffset <= 1; dayOffset++) {
     const d = new Date(now.getTime() - dayOffset * 86_400_000);
     const sessDir = join(
@@ -971,10 +992,7 @@ function getCodexRateLimits() {
     let files;
     try { files = readdirSync(sessDir).filter((f) => f.endsWith(".jsonl")).sort().reverse(); }
     catch { continue; }
-    if (dayOffset === 0 && files.length > 0) todayHasFiles = true;
 
-    // 당일 모든 세션 파일을 스캔해 limit_id별 가장 최신 버킷을 병합
-    // (파일 목록은 이름 역순 정렬 → 최신 세션 우선)
     const mergedBuckets = {};
     for (const file of files) {
       try {
@@ -985,7 +1003,7 @@ function getCodexRateLimits() {
             const evt = JSON.parse(line);
             const rl = evt?.payload?.rate_limits;
             if (rl?.limit_id && !mergedBuckets[rl.limit_id]) {
-              // limit_id별로 첫 발견(=해당 세션의 가장 최신 이벤트)만 기록
+              // 실제 rate_limits: limit_id별 최신 이벤트만 기록
               mergedBuckets[rl.limit_id] = {
                 limitId: rl.limit_id, limitName: rl.limit_name,
                 primary: rl.primary, secondary: rl.secondary,
@@ -994,18 +1012,33 @@ function getCodexRateLimits() {
                 contextWindow: evt.payload?.info?.model_context_window,
                 timestamp: evt.timestamp,
               };
+            } else if (dayOffset === 0 && !rl && evt?.payload?.info?.total_token_usage && !syntheticBucket) {
+              // 오늘 token_count: 합성 버킷 (rate_limits가 null일 때 행 활성화용)
+              syntheticBucket = {
+                limitId: "codex", limitName: "codex-session",
+                primary: null, secondary: null,
+                credits: null,
+                tokens: evt.payload.info.total_token_usage,
+                contextWindow: evt.payload.info.model_context_window,
+                timestamp: evt.timestamp,
+              };
             }
           } catch { /* 라인 파싱 실패 무시 */ }
           if (Object.keys(mergedBuckets).length >= CODEX_MIN_BUCKETS) break;
         }
       } catch { /* 파일 읽기 실패 무시 */ }
     }
-    if (Object.keys(mergedBuckets).length > 0) return mergedBuckets;
-
-    // 오늘 세션 파일이 존재하지만 rate_limits가 없으면 어제 stale 데이터로 폴백하지 않음
-    if (todayHasFiles && dayOffset === 0) return null;
+    // 실제 rate_limits 발견 → 오늘 토큰 데이터 병합 후 즉시 반환
+    if (Object.keys(mergedBuckets).length > 0) {
+      if (syntheticBucket) {
+        const main = mergedBuckets.codex || mergedBuckets[Object.keys(mergedBuckets)[0]];
+        if (main && !main.tokens) main.tokens = syntheticBucket.tokens;
+      }
+      return mergedBuckets;
+    }
   }
-  return null;
+  // 실제 rate_limits 없음 → 합성 버킷이라도 반환 (행 활성화)
+  return syntheticBucket ? { codex: syntheticBucket } : null;
 }
 
 // ============================================================================

package/package.json

@@ -1,51 +1,56 @@
-{
-  "name": "triflux",
-  "version": "2.5.1",
-  "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.1",
+  "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"
+  ]
+}