@triflux/core 10.1.0 → 10.25.1

package/hub/middleware/quota-middleware.mjs

@@ -0,0 +1,70 @@
+const FAILURE_STATUSES = new Set(["quota_hit", "error"]);
+
+function buildFailureRecord(result = {}) {
+  const failure = {
+    id: result.id ?? "unknown",
+    status: result.status ?? "unknown",
+  };
+
+  if (Number.isFinite(result.http)) {
+    failure.http = result.http;
+  }
+
+  if (typeof result.message === "string" && result.message.length > 0) {
+    failure.message = result.message;
+  }
+
+  if (result.headers && Object.keys(result.headers).length > 0) {
+    failure.headers = result.headers;
+  }
+
+  return failure;
+}
+
+export function summarizeQuotaResults(results = []) {
+  const metrics = {
+    checked: results.length,
+    ok: 0,
+    quotaHit: 0,
+    error: 0,
+    failed: 0,
+  };
+  const failures = [];
+
+  for (const result of results) {
+    const status = result?.status ?? "unknown";
+
+    if (status === "ok") {
+      metrics.ok += 1;
+    } else if (status === "quota_hit") {
+      metrics.quotaHit += 1;
+    } else if (status === "error") {
+      metrics.error += 1;
+    }
+
+    if (FAILURE_STATUSES.has(status)) {
+      failures.push(buildFailureRecord(result));
+    }
+  }
+
+  metrics.failed = failures.length;
+  return { metrics, failures };
+}
+
+export function logQuotaRefreshFailures(logger, results = []) {
+  const { metrics, failures } = summarizeQuotaResults(results);
+  if (failures.length === 0) {
+    return { logged: false, metrics, failures };
+  }
+
+  logger.warn(
+    {
+      tag: "hub-quota",
+      metrics,
+      failures,
+    },
+    "broker.quota_refresh_degraded",
+  );
+
+  return { logged: true, metrics, failures };
+}

package/hub/middleware/request-logger.mjs

@@ -10,14 +10,18 @@
  * 각 요청에 correlationId를 할당하고, 응답 완료 시 구조화 로그를 남긴다.
  * health/status 체크는 로깅을 건너뛴다.
  */
-import { withRequestContext, getCorrelationId } from '../../scripts/lib/context.mjs';
-import { createModuleLogger } from '../../scripts/lib/logger.mjs';
-import { createContextMonitor } from '../../hud/context-monitor.mjs';
 
-const log = createModuleLogger('hub');
+import { createContextMonitor } from "../../hud/context-monitor.mjs";
+import {
+  getCorrelationId,
+  withRequestContext,
+} from "../../scripts/lib/context.mjs";
+import { createModuleLogger } from "../../scripts/lib/logger.mjs";
+
+const log = createModuleLogger("hub");
 const contextMonitor = createContextMonitor();
 
-const SKIP_PATHS = new Set(['/health', '/healthz', '/status', '/ready']);
+const SKIP_PATHS = new Set(["/health", "/healthz", "/status", "/ready"]);
 const MAX_CAPTURE_BYTES = 256 * 1024;
 
 /**
@@ -35,8 +39,8 @@ export function wrapRequestHandler(handler) {
     }
 
     const correlationId =
-      req.headers['x-correlation-id'] ||
-      req.headers['x-request-id'] ||
+      req.headers["x-correlation-id"] ||
+      req.headers["x-request-id"] ||
       undefined; // withRequestContext will generate one
 
     withRequestContext(
@@ -51,9 +55,11 @@ export function wrapRequestHandler(handler) {
         let reqBytes = 0;
         let reqOverflow = false;
 
-        req.on('data', (chunk) => {
+        req.on("data", (chunk) => {
           if (reqOverflow) return;
-          const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+          const buf = Buffer.isBuffer(chunk)
+            ? chunk
+            : Buffer.from(String(chunk));
           reqBytes += buf.length;
           if (reqBytes > MAX_CAPTURE_BYTES) {
             reqOverflow = true;
@@ -72,7 +78,9 @@ export function wrapRequestHandler(handler) {
 
         function captureResponseChunk(chunk) {
           if (resOverflow || chunk == null) return;
-          const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+          const buf = Buffer.isBuffer(chunk)
+            ? chunk
+            : Buffer.from(String(chunk));
           resBytes += buf.length;
           if (resBytes > MAX_CAPTURE_BYTES) {
             resOverflow = true;
@@ -94,28 +102,38 @@ export function wrapRequestHandler(handler) {
 
         // 응답 헤더에 상관 ID 포함
         const cid = getCorrelationId();
-        if (cid) res.setHeader('X-Correlation-ID', cid);
+        if (cid) res.setHeader("X-Correlation-ID", cid);
 
         // 응답 완료 시 로깅
-        res.on('finish', () => {
-          const duration = Number(process.hrtime.bigint() - startTime) / 1_000_000;
-          const level = res.statusCode >= 500 ? 'error'
-            : res.statusCode >= 400 ? 'warn'
-            : 'info';
-          const reqBodyText = reqOverflow ? '' : Buffer.concat(reqChunks).toString('utf8');
-          const resBodyText = resOverflow ? '' : Buffer.concat(resChunks).toString('utf8');
+        res.on("finish", () => {
+          const duration =
+            Number(process.hrtime.bigint() - startTime) / 1_000_000;
+          const level =
+            res.statusCode >= 500
+              ? "error"
+              : res.statusCode >= 400
+                ? "warn"
+                : "info";
+          const reqBodyText = reqOverflow
+            ? ""
+            : Buffer.concat(reqChunks).toString("utf8");
+          const resBodyText = resOverflow
+            ? ""
+            : Buffer.concat(resChunks).toString("utf8");
           const tokenSummary = contextMonitor.record({
             requestBody: reqBodyText,
-            requestBytes: reqBytes || Number(req.headers['content-length'] || 0),
+            requestBytes:
+              reqBytes || Number(req.headers["content-length"] || 0),
             responseBody: resBodyText,
-            responseBytes: resBytes || Number(res.getHeader('content-length') || 0),
+            responseBytes:
+              resBytes || Number(res.getHeader("content-length") || 0),
           });
 
           log[level](
             {
               status: res.statusCode,
               duration: Math.round(duration * 100) / 100,
-              contentLength: res.getHeader('content-length') || 0,
+              contentLength: res.getHeader("content-length") || 0,
               tokenUsage: {
                 request: tokenSummary.requestTokens,
                 response: tokenSummary.responseTokens,
@@ -125,23 +143,32 @@ export function wrapRequestHandler(handler) {
                 overheadMs: tokenSummary.overheadMs,
               },
             },
-            'http.response',
+            "http.response",
           );
 
-          if (tokenSummary.warningLevel === 'critical') {
+          if (tokenSummary.warningLevel === "critical") {
             log.error(
-              { context: tokenSummary.display, message: tokenSummary.warningMessage },
-              'context.critical',
+              {
+                context: tokenSummary.display,
+                message: tokenSummary.warningMessage,
+              },
+              "context.critical",
             );
-          } else if (tokenSummary.warningLevel === 'warn') {
+          } else if (tokenSummary.warningLevel === "warn") {
             log.warn(
-              { context: tokenSummary.display, message: tokenSummary.warningMessage },
-              'context.warn',
+              {
+                context: tokenSummary.display,
+                message: tokenSummary.warningMessage,
+              },
+              "context.warn",
             );
-          } else if (tokenSummary.warningLevel === 'info') {
+          } else if (tokenSummary.warningLevel === "info") {
             log.info(
-              { context: tokenSummary.display, message: tokenSummary.warningMessage },
-              'context.info',
+              {
+                context: tokenSummary.display,
+                message: tokenSummary.warningMessage,
+              },
+              "context.info",
             );
           }
         });
@@ -152,10 +179,10 @@ export function wrapRequestHandler(handler) {
   };
 }
 
-function getRequestPath(url = '/') {
+function getRequestPath(url = "/") {
   try {
-    return new URL(url, 'http://127.0.0.1').pathname;
+    return new URL(url, "http://127.0.0.1").pathname;
   } catch {
-    return String(url).replace(/\?.*/, '') || '/';
+    return String(url).replace(/\?.*/, "") || "/";
   }
 }

package/hub/paths.mjs

@@ -1,15 +1,15 @@
 // hub/paths.mjs — triflux 워킹 디렉토리 경로 상수
 
-import { mkdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
 
-export const TFX_WORK_DIR = '.tfx';
-export const TFX_PLANS_DIR = join(TFX_WORK_DIR, 'plans');
-export const TFX_REPORTS_DIR = join(TFX_WORK_DIR, 'reports');
-export const TFX_HANDOFFS_DIR = join(TFX_WORK_DIR, 'handoffs');
-export const TFX_LOGS_DIR = join(TFX_WORK_DIR, 'logs');
-export const TFX_STATE_DIR = join(TFX_WORK_DIR, 'state');
-export const TFX_FULLCYCLE_DIR = join(TFX_WORK_DIR, 'fullcycle');
+export const TFX_WORK_DIR = ".tfx";
+export const TFX_PLANS_DIR = join(TFX_WORK_DIR, "plans");
+export const TFX_REPORTS_DIR = join(TFX_WORK_DIR, "reports");
+export const TFX_HANDOFFS_DIR = join(TFX_WORK_DIR, "handoffs");
+export const TFX_LOGS_DIR = join(TFX_WORK_DIR, "logs");
+export const TFX_STATE_DIR = join(TFX_WORK_DIR, "state");
+export const TFX_FULLCYCLE_DIR = join(TFX_WORK_DIR, "fullcycle");
 
 /**
  * triflux 워킹 디렉토리 구조를 보장한다.

package/hub/pipeline/gates/confidence.mjs

@@ -4,11 +4,11 @@
 // 5단계 확신도 검증: >=90% proceed / 70-89% alternative / <70% abort
 
 export const CRITERIA = [
-  { id: 'no_duplicate',  label: '중복 구현 없는지?', weight: 0.25 },
-  { id: 'architecture',  label: '아키텍처 준수?',    weight: 0.25 },
-  { id: 'docs_verified', label: '공식 문서 확인?',   weight: 0.20 },
-  { id: 'oss_reference', label: 'OSS 레퍼런스?',    weight: 0.15 },
-  { id: 'root_cause',    label: '근본 원인 파악?',   weight: 0.15 },
+  { id: "no_duplicate", label: "중복 구현 없는지?", weight: 0.25 },
+  { id: "architecture", label: "아키텍처 준수?", weight: 0.25 },
+  { id: "docs_verified", label: "공식 문서 확인?", weight: 0.2 },
+  { id: "oss_reference", label: "OSS 레퍼런스?", weight: 0.15 },
+  { id: "root_cause", label: "근본 원인 파악?", weight: 0.15 },
 ];
 
 /**
@@ -22,18 +22,31 @@ export function runConfidenceCheck(planArtifact, context = {}) {
   if (!planArtifact) {
     return {
       score: 0,
-      breakdown: CRITERIA.map(c => ({ id: c.id, label: c.label, weight: c.weight, score: 0, passed: false })),
-      decision: 'abort',
-      reasoning: 'planArtifact가 제공되지 않았습니다.',
+      breakdown: CRITERIA.map((c) => ({
+        id: c.id,
+        label: c.label,
+        weight: c.weight,
+        score: 0,
+        passed: false,
+      })),
+      decision: "abort",
+      reasoning: "planArtifact가 제공되지 않았습니다.",
     };
   }
 
   const checks = context.checks || {};
 
-  const breakdown = CRITERIA.map(c => {
+  const breakdown = CRITERIA.map((c) => {
     const raw = checks[c.id];
-    const score = typeof raw === 'number' ? Math.max(0, Math.min(1, raw)) : (raw ? 1 : 0);
-    return { id: c.id, label: c.label, weight: c.weight, score, passed: score >= 0.7 };
+    const score =
+      typeof raw === "number" ? Math.max(0, Math.min(1, raw)) : raw ? 1 : 0;
+    return {
+      id: c.id,
+      label: c.label,
+      weight: c.weight,
+      score,
+      passed: score >= 0.7,
+    };
   });
 
   const totalScore = Math.round(
@@ -42,15 +55,21 @@ export function runConfidenceCheck(planArtifact, context = {}) {
 
   let decision, reasoning;
   if (totalScore >= 90) {
-    decision = 'proceed';
+    decision = "proceed";
     reasoning = `확신도 ${totalScore}%: 모든 기준 충족. 실행 진행.`;
   } else if (totalScore >= 70) {
-    decision = 'alternative';
+    decision = "alternative";
     reasoning = `확신도 ${totalScore}%: 일부 기준 미달. 대안 검토 필요.`;
   } else {
-    decision = 'abort';
+    decision = "abort";
     reasoning = `확신도 ${totalScore}%: 기준 미달. 실행 중단.`;
   }
 
-  return { score: totalScore, breakdown, decision, reasoning, needsReview: decision === 'alternative' };
+  return {
+    score: totalScore,
+    breakdown,
+    decision,
+    reasoning,
+    needsReview: decision === "alternative",
+  };
 }

package/hub/pipeline/gates/consensus.mjs

@@ -14,8 +14,9 @@ export const STAGE_THRESHOLDS = {
 
 /** 환경변수 기반 기본 임계값 (기본 75) */
 function getDefaultThreshold() {
-  const env = typeof process !== 'undefined' && process.env?.TRIFLUX_CONSENSUS_THRESHOLD;
-  if (env != null && env !== '') {
+  const env =
+    typeof process !== "undefined" && process.env?.TRIFLUX_CONSENSUS_THRESHOLD;
+  if (env != null && env !== "") {
     const parsed = Number(env);
     if (!Number.isNaN(parsed) && parsed >= 0 && parsed <= 100) return parsed;
   }
@@ -30,14 +31,19 @@ function getDefaultThreshold() {
  * @param {string} [mode] - 실행 모드 ('supervised' | 기타)
  * @returns {'proceed' | 'proceed_warn' | 'retry' | 'escalate' | 'abort'}
  */
-export function evaluateQualityBranch(successRate, retryCount, maxRetries, mode) {
-  if (successRate >= 90) return 'proceed';
-  if (successRate >= 75) return 'proceed_warn';
+export function evaluateQualityBranch(
+  successRate,
+  retryCount,
+  maxRetries,
+  mode,
+) {
+  if (successRate >= 90) return "proceed";
+  if (successRate >= 75) return "proceed_warn";
 
   // <75%: 재시도 가능 여부에 따라 분기
-  if (retryCount < maxRetries) return 'retry';
-  if (mode === 'supervised') return 'escalate';
-  return 'abort';
+  if (retryCount < maxRetries) return "retry";
+  if (mode === "supervised") return "escalate";
+  return "abort";
 }
 
 /**
@@ -56,8 +62,8 @@ export function evaluateConsensus(results, options = {}) {
     return {
       successRate: 0,
       threshold: options.threshold ?? getDefaultThreshold(),
-      decision: 'abort',
-      reasoning: '평가 대상 결과가 없습니다.',
+      decision: "abort",
+      reasoning: "평가 대상 결과가 없습니다.",
       results: [],
     };
   }
@@ -67,14 +73,20 @@ export function evaluateConsensus(results, options = {}) {
   const mode = options.mode;
 
   // 임계값 결정: 직접 지정 > stage별 > 환경변수 > 기본 75
-  const threshold = options.threshold
-    ?? (options.stage && STAGE_THRESHOLDS[options.stage])
-    ?? getDefaultThreshold();
+  const threshold =
+    options.threshold ??
+    (options.stage && STAGE_THRESHOLDS[options.stage]) ??
+    getDefaultThreshold();
 
-  const successCount = results.filter(r => r.success).length;
+  const successCount = results.filter((r) => r.success).length;
   const successRate = Math.round((successCount / results.length) * 100);
 
-  const decision = evaluateQualityBranch(successRate, retryCount, maxRetries, mode);
+  const decision = evaluateQualityBranch(
+    successRate,
+    retryCount,
+    maxRetries,
+    mode,
+  );
 
   const reasoningMap = {
     proceed: `합의율 ${successRate}% (>= 90%): 전원 합의. 진행.`,

package/hub/pipeline/gates/index.mjs

@@ -1,5 +1,9 @@
 // hub/pipeline/gates/index.mjs — Quality Gates re-export
 
-export { CRITERIA, runConfidenceCheck } from './confidence.mjs';
-export { RED_FLAGS, QUESTIONS, runSelfCheck } from './selfcheck.mjs';
-export { STAGE_THRESHOLDS, evaluateQualityBranch, evaluateConsensus } from './consensus.mjs';
+export { CRITERIA, runConfidenceCheck } from "./confidence.mjs";
+export {
+  evaluateConsensus,
+  evaluateQualityBranch,
+  STAGE_THRESHOLDS,
+} from "./consensus.mjs";
+export { QUESTIONS, RED_FLAGS, runSelfCheck } from "./selfcheck.mjs";

package/hub/pipeline/gates/selfcheck.mjs

@@ -4,20 +4,56 @@
 // 4대 필수 질문 + 7대 할루시네이션 Red Flag 탐지
 
 export const RED_FLAGS = [
-  { id: 'test_pass_no_output',  pattern: /테스트\s*(?:가\s*)?통과/,  label: '"테스트 통과" (출력 없이)' },
-  { id: 'everything_works',     pattern: /모든\s*게?\s*작동/,        label: '"모든게 작동" (증거 없이)' },
-  { id: 'no_changes_with_diff', pattern: /변경\s*(?:사항\s*)?없/,    label: '"변경 없음" (diff 있는데)' },
-  { id: 'backward_compatible',  pattern: /호환성\s*(?:이\s*)?유지/,  label: '"호환성 유지" (검증 없이)' },
-  { id: 'performance_improved', pattern: /성능\s*(?:이\s*)?개선/,    label: '"성능 개선" (벤치마크 없이)' },
-  { id: 'security_enhanced',    pattern: /보안\s*(?:이\s*)?강화/,    label: '"보안 강화" (증거 없이)' },
-  { id: 'error_handling_done',  pattern: /에러\s*처리\s*(?:가\s*)?완료/, label: '"에러 처리 완료" (catch 블록만)' },
+  {
+    id: "test_pass_no_output",
+    pattern: /테스트\s*(?:가\s*)?통과/,
+    label: '"테스트 통과" (출력 없이)',
+  },
+  {
+    id: "everything_works",
+    pattern: /모든\s*게?\s*작동/,
+    label: '"모든게 작동" (증거 없이)',
+  },
+  {
+    id: "no_changes_with_diff",
+    pattern: /변경\s*(?:사항\s*)?없/,
+    label: '"변경 없음" (diff 있는데)',
+  },
+  {
+    id: "backward_compatible",
+    pattern: /호환성\s*(?:이\s*)?유지/,
+    label: '"호환성 유지" (검증 없이)',
+  },
+  {
+    id: "performance_improved",
+    pattern: /성능\s*(?:이\s*)?개선/,
+    label: '"성능 개선" (벤치마크 없이)',
+  },
+  {
+    id: "security_enhanced",
+    pattern: /보안\s*(?:이\s*)?강화/,
+    label: '"보안 강화" (증거 없이)',
+  },
+  {
+    id: "error_handling_done",
+    pattern: /에러\s*처리\s*(?:가\s*)?완료/,
+    label: '"에러 처리 완료" (catch 블록만)',
+  },
 ];
 
 export const QUESTIONS = [
-  { id: 'tests_passing',    label: '모든 테스트 통과?',   evidenceKey: 'testOutput' },
-  { id: 'requirements_met', label: '모든 요구사항 충족?', evidenceKey: 'requirementChecklist' },
-  { id: 'no_assumptions',   label: '검증 없는 가정?',    evidenceKey: 'references' },
-  { id: 'evidence_provided', label: '증거 있는가?',       evidenceKey: 'artifacts' },
+  {
+    id: "tests_passing",
+    label: "모든 테스트 통과?",
+    evidenceKey: "testOutput",
+  },
+  {
+    id: "requirements_met",
+    label: "모든 요구사항 충족?",
+    evidenceKey: "requirementChecklist",
+  },
+  { id: "no_assumptions", label: "검증 없는 가정?", evidenceKey: "references" },
+  { id: "evidence_provided", label: "증거 있는가?", evidenceKey: "artifacts" },
 ];
 
 /**
@@ -34,10 +70,10 @@ function detectRedFlags(text, context = {}) {
     if (!rf.pattern.test(text)) continue;
 
     // "변경 없음"은 실제 diff가 있을 때만 Red Flag
-    if (rf.id === 'no_changes_with_diff' && !context.hasDiff) continue;
+    if (rf.id === "no_changes_with_diff" && !context.hasDiff) continue;
 
     // "테스트 통과"는 testOutput 증거가 없을 때만 Red Flag
-    if (rf.id === 'test_pass_no_output' && evidence.testOutput) continue;
+    if (rf.id === "test_pass_no_output" && evidence.testOutput) continue;
 
     // 기타 Red Flag는 해당 id의 반증이 있으면 스킵
     if (evidence[rf.id]) continue;
@@ -58,24 +94,26 @@ function detectRedFlags(text, context = {}) {
  * @returns {{ passed: boolean, score: number, flags: Array, checklist: Array }}
  */
 export function runSelfCheck(execResult, verifyResult, requirements = {}) {
-  const normalize = (v) => typeof v === 'string' ? v : (v != null ? JSON.stringify(v) : '');
-  const text = [normalize(execResult), normalize(verifyResult)].join('\n');
+  const normalize = (v) =>
+    typeof v === "string" ? v : v != null ? JSON.stringify(v) : "";
+  const text = [normalize(execResult), normalize(verifyResult)].join("\n");
 
   const flags = detectRedFlags(text, requirements);
 
   const evidence = requirements.evidence || {};
-  const checklist = QUESTIONS.map(q => {
+  const checklist = QUESTIONS.map((q) => {
     const ev = evidence[q.evidenceKey];
-    const passed = ev != null && (typeof ev === 'string' ? ev.trim().length > 0 : true);
+    const passed =
+      ev != null && (typeof ev === "string" ? ev.trim().length > 0 : true);
     return { id: q.id, label: q.label, passed, evidence: ev || null };
   });
 
-  const allQuestionsPassed = checklist.every(q => q.passed);
+  const allQuestionsPassed = checklist.every((q) => q.passed);
   const passed = flags.length === 0 && allQuestionsPassed;
 
   // 점수: 기본 100, Red Flag당 -15, 실패 질문당 -20
   const flagPenalty = flags.length * 15;
-  const questionPenalty = checklist.filter(q => !q.passed).length * 20;
+  const questionPenalty = checklist.filter((q) => !q.passed).length * 20;
   const score = Math.max(0, 100 - flagPenalty - questionPenalty);
 
   return { passed, score, flags, checklist };