@triflux/core 10.0.0-alpha.1

package/hub/gemini-adapter.mjs

@@ -0,0 +1,179 @@
+// hub/gemini-adapter.mjs — Gemini CLI 방어 계층
+// codex-adapter.mjs와 동일 패턴, cli-adapter-base 공통 인터페이스 사용
+
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { withRetry } from './workers/worker-utils.mjs';
+import { whichCommandAsync } from './platform.mjs';
+import {
+  createCircuitBreaker,
+  createResult,
+  appendWarnings,
+  normalizePathForShell,
+  shellQuote,
+  runProcess,
+} from './cli-adapter-base.mjs';
+
+const breaker = createCircuitBreaker();
+
+// ── Gemini-specific stall inference ─────────────────────────────
+
+function inferStallMode(stdout, stderr) {
+  const text = `${stdout}\n${stderr}`.toLowerCase();
+  if (/(unauthorized|forbidden|auth|login|token|credential|api.?key)/u.test(text)) return 'auth_stall';
+  if (/\bmcp\b|playwright|tavily|brave|sequential|server/u.test(text)) return 'mcp_stall';
+  return 'timeout';
+}
+
+// ── Preflight ───────────────────────────────────────────────────
+
+async function runPreflight(opts = {}) {
+  const geminiPath = await whichCommandAsync('gemini');
+  if (!geminiPath) {
+    return {
+      geminiPath: null,
+      warnings: ['Gemini CLI not found. Install Gemini and ensure `gemini` is available on PATH.'],
+      excludeMcpServers: [],
+      ok: false,
+    };
+  }
+
+  const warnings = [];
+  const excludeMcpServers = [];
+
+  for (const name of Array.isArray(opts.mcpServers) ? opts.mcpServers : []) {
+    const server = String(name ?? '').trim();
+    if (!server) continue;
+    // Gemini MCP health는 best-effort: 실행 시점에 --allowed-mcp-server-names로 필터링
+    // 사전 probe는 수행하지 않음 (gemini가 자체적으로 graceful degrade)
+  }
+
+  return { geminiPath, warnings, excludeMcpServers, ok: true };
+}
+
+// ── Command building ────────────────────────────────────────────
+
+function buildGeminiCommand(prompt, resultFile, opts = {}) {
+  const parts = ['gemini'];
+
+  if (opts.model) parts.push('--model', shellQuote(opts.model));
+  parts.push('--yolo');
+
+  const allowed = Array.isArray(opts.allowedMcpServers) ? opts.allowedMcpServers : [];
+  const excluded = Array.isArray(opts.excludeMcpServers) ? opts.excludeMcpServers : [];
+  const filtered = allowed.filter((name) => !excluded.includes(name));
+  if (filtered.length) {
+    parts.push('--allowed-mcp-server-names', ...filtered.map((n) => shellQuote(n)));
+  }
+
+  parts.push('--prompt', shellQuote(prompt));
+  parts.push('--output-format', 'text');
+
+  if (resultFile) {
+    return `${parts.join(' ')} > ${shellQuote(normalizePathForShell(resultFile))} 2>${shellQuote(normalizePathForShell(resultFile + '.err'))}`;
+  }
+
+  return parts.join(' ');
+}
+
+function buildAttempts(opts, preflight) {
+  const timeout = Number.isFinite(opts.timeout) ? opts.timeout : 900_000;
+  const base = {
+    timeout,
+    model: opts.model,
+    allowedMcpServers: Array.isArray(opts.mcpServers) ? [...opts.mcpServers] : [],
+    excludeMcpServers: [...(preflight.excludeMcpServers || [])],
+  };
+  if (opts.retryOnFail === false) return [base];
+  return [
+    base,
+    { ...base, timeout: timeout * 2, allowedMcpServers: [] },
+  ];
+}
+
+// ── Public: buildExecArgs ───────────────────────────────────────
+
+export function buildExecArgs(opts = {}) {
+  const prompt = typeof opts.prompt === 'string' ? opts.prompt : '';
+  return buildGeminiCommand(prompt, opts.resultFile || null, {
+    model: opts.model,
+    allowedMcpServers: opts.mcpServers,
+  });
+}
+
+// ── Execution ───────────────────────────────────────────────────
+
+async function runGemini(prompt, workdir, preflight, attempt) {
+  const dir = join(tmpdir(), 'triflux-gemini-exec');
+  mkdirSync(dir, { recursive: true });
+  const resultFile = join(dir, `gemini-${Date.now()}-${Math.random().toString(36).slice(2)}.txt`);
+  const command = buildGeminiCommand(prompt, resultFile, {
+    model: attempt.model,
+    allowedMcpServers: attempt.allowedMcpServers,
+    excludeMcpServers: attempt.excludeMcpServers,
+  });
+  return runProcess(command, workdir, attempt.timeout, { resultFile, inferStallMode });
+}
+
+// ── Public API ──────────────────────────────────────────────────
+
+export function getCircuitState(now) {
+  return breaker.getState(now);
+}
+
+export async function execute(opts = {}) {
+  const entry = breaker.canExecute();
+  if (!entry.allowed) {
+    return createResult(false, { fellBack: true, failureMode: 'circuit_open' });
+  }
+
+  const preflight = await runPreflight({ mcpServers: opts.mcpServers });
+  if (!preflight.ok) {
+    breaker.clearTrial();
+    breaker.recordFailure(entry.halfOpen);
+    return createResult(false, {
+      stderr: appendWarnings('', preflight.warnings),
+      fellBack: opts.fallbackToClaude !== false,
+      failureMode: 'crash',
+    });
+  }
+
+  const attempts = buildAttempts(opts, preflight);
+  let attemptIndex = 0;
+  let lastResult = createResult(false);
+
+  try {
+    lastResult = await withRetry(async () => {
+      const result = await runGemini(opts.prompt || '', opts.workdir || process.cwd(), preflight, attempts[attemptIndex]);
+      const current = { ...result, stderr: appendWarnings(result.stderr, preflight.warnings), retried: attemptIndex > 0 };
+      const canRetry = !current.ok && attemptIndex < attempts.length - 1;
+      attemptIndex += 1;
+      if (!canRetry) return current;
+      const error = new Error('retry');
+      error.retryable = true;
+      error.result = current;
+      throw error;
+    }, {
+      maxAttempts: attempts.length,
+      baseDelayMs: 250,
+      maxDelayMs: 750,
+      shouldRetry: (error) => error?.retryable === true,
+    });
+  } catch (error) {
+    lastResult = error?.result || createResult(false, { stderr: String(error?.message || error) });
+  }
+
+  if (lastResult.ok) {
+    breaker.reset();
+    return lastResult;
+  }
+
+  breaker.recordFailure(entry.halfOpen);
+  return {
+    ...lastResult,
+    retried: attempts.length > 1,
+    fellBack: opts.fallbackToClaude !== false,
+  };
+}

package/hub/hitl.mjs

@@ -0,0 +1,143 @@
+// hub/hitl.mjs — Human-in-the-Loop 매니저
+// 사용자 입력 요청/응답, 타임아웃 자동 처리
+
+/**
+ * HITL 매니저 생성
+ * @param {object} store — createStore() 반환 객체
+ * @param {object} router — createRouter() 반환 객체
+ */
+export function createHitlManager(store, router = null) {
+  function forwardHumanResponse({ requesterAgent, requestId, action, content, submittedBy, correlationId, traceId, priority }) {
+    if (!router?.handlePublish) {
+      throw new Error('router.handlePublish is required for HITL forwarding');
+    }
+    return router.handlePublish({
+      from: 'hub:hitl',
+      to: requesterAgent,
+      topic: 'human.response',
+      priority,
+      ttl_ms: 300000,
+      payload: { request_id: requestId, action, content, submitted_by: submittedBy },
+      correlation_id: correlationId,
+      trace_id: traceId,
+      message_type: 'human_response',
+    });
+  }
+
+  return {
+    /**
+     * 사용자에게 입력 요청 생성
+     * 터미널에 알림 출력 후 pending 상태로 저장
+     */
+    requestHumanInput({
+      requester_agent, kind, prompt, requested_schema = {},
+      deadline_ms, default_action, channel_preference = 'terminal',
+      correlation_id, trace_id,
+    }) {
+      const result = store.insertHumanRequest({
+        requester_agent, kind, prompt, requested_schema,
+        deadline_ms, default_action,
+        correlation_id, trace_id,
+      });
+
+      // 터미널 알림 (stderr — stdout은 MCP 용)
+      const kindLabel = { captcha: 'CAPTCHA', approval: '승인', credential: '자격증명', choice: '선택', text: '텍스트' };
+      process.stderr.write(
+        `\n[tfx-hub] 사용자 입력 요청 (${kindLabel[kind] || kind})\n` +
+        `  요청자: ${requester_agent}\n` +
+        `  내용: ${prompt}\n` +
+        `  ID: ${result.request_id}\n` +
+        `  제한: ${Math.round(deadline_ms / 1000)}초\n\n`,
+      );
+
+      return { ok: true, data: result };
+    },
+
+    /**
+     * 사용자 입력 응답 제출
+     * 유효성 검증 → 상태 업데이트 → 요청자에게 응답 메시지 전달
+     */
+    submitHumanInput({ request_id, action, content = null, submitted_by = 'human' }) {
+      // 요청 조회
+      const hr = store.getHumanRequest(request_id);
+      if (!hr) {
+        return { ok: false, error: { code: 'NOT_FOUND', message: `요청 없음: ${request_id}` } };
+      }
+      if (hr.state !== 'pending') {
+        return { ok: false, error: { code: 'ALREADY_HANDLED', message: `이미 처리됨: ${hr.state}` } };
+      }
+
+      // 상태 매핑
+      const stateMap = { accept: 'accepted', decline: 'declined', cancel: 'cancelled' };
+      const newState = stateMap[action];
+      if (!newState) {
+        return { ok: false, error: { code: 'INVALID_ACTION', message: `잘못된 action: ${action}` } };
+      }
+
+      // DB 업데이트
+      store.updateHumanRequest(request_id, newState, content);
+
+      // 요청자에게 응답 메시지 전달
+      let forwardedMessageId = null;
+      if (action === 'accept' || action === 'decline') {
+        const published = forwardHumanResponse({
+          requesterAgent: hr.requester_agent,
+          requestId: request_id,
+          action,
+          content,
+          submittedBy: submitted_by,
+          correlationId: hr.correlation_id,
+          traceId: hr.trace_id,
+          priority: 7,
+        });
+        forwardedMessageId = published.data?.message_id || null;
+      }
+
+      return {
+        ok: true,
+        data: { request_id, new_state: newState, forwarded_message_id: forwardedMessageId },
+      };
+    },
+
+    /**
+     * 만료된 요청 자동 처리
+     * deadline 초과 시 default_action 적용
+     */
+    checkTimeouts() {
+      const pending = store.getPendingHumanRequests();
+      const now = Date.now();
+      const expired = pending.filter(hr => hr.deadline_ms <= now);
+      if (!expired.length) return 0;
+
+      const expireRequests = () => {
+        for (const hr of expired) {
+          store.updateHumanRequest(hr.request_id, 'timed_out', null);
+          if (hr.default_action === 'timeout_continue') {
+            forwardHumanResponse({
+              requesterAgent: hr.requester_agent,
+              requestId: hr.request_id,
+              action: 'timeout_continue',
+              content: null,
+              submittedBy: 'system',
+              correlationId: hr.correlation_id,
+              traceId: hr.trace_id,
+              priority: 5,
+            });
+          }
+        }
+        return expired.length;
+      };
+
+      const processExpired = store.db?.transaction
+        ? store.db.transaction(expireRequests)
+        : expireRequests;
+
+      return processExpired();
+    },
+
+    /** 대기 중인 요청 목록 */
+    getPendingRequests() {
+      return store.getPendingHumanRequests();
+    },
+  };
+}

package/hub/intent.mjs

@@ -0,0 +1,193 @@
+// hub/intent.mjs — Intent Classification Engine
+// 사용자 요청의 "진짜 의도"를 분석 → 카테고리 분류 → 최적 에이전트/모델 자동 선택
+
+import { execFileSync } from 'node:child_process';
+import crypto from 'node:crypto';
+import { whichCommand } from './platform.mjs';
+
+/** 캐시 엔트리: { category, confidence, ts } */
+const _intentCache = new Map();
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5분
+
+/** codex 설치 여부 (프로세스당 1회 확인) */
+let _codexAvailable = null;
+
+function _isCodexAvailable() {
+  if (_codexAvailable !== null) return _codexAvailable;
+  _codexAvailable = Boolean(whichCommand('codex'));
+  return _codexAvailable;
+}
+
+function _promptHash(prompt) {
+  return crypto.createHash('md5').update(prompt).digest('hex');
+}
+
+function _getCached(hash) {
+  const entry = _intentCache.get(hash);
+  if (!entry) return null;
+  if (Date.now() - entry.ts > CACHE_TTL_MS) {
+    _intentCache.delete(hash);
+    return null;
+  }
+  return entry;
+}
+
+function _tryCodexClassify(prompt) {
+  try {
+    const raw = execFileSync(
+      'codex',
+      ['exec', `Classify intent: ${prompt}. Reply JSON: {intent, confidence}`],
+      { timeout: 8000, encoding: 'utf8' }
+    );
+    // JSON 블록 추출 (응답에 다른 텍스트가 섞일 수 있음)
+    const match = raw.match(/\{[\s\S]*?\}/);
+    if (!match) return null;
+    const parsed = JSON.parse(match[0]);
+    const intent = typeof parsed.intent === 'string' ? parsed.intent : null;
+    const confidence = typeof parsed.confidence === 'number' ? parsed.confidence : null;
+    if (!intent || confidence === null) return null;
+    // intent가 알려진 카테고리여야 함
+    if (!INTENT_CATEGORIES[intent]) return null;
+    return { category: intent, confidence };
+  } catch {
+    return null;
+  }
+}
+
+/** triflux 특화 의도 카테고리 (10개) */
+export const INTENT_CATEGORIES = {
+  implement:  { agent: 'executor',       mcp: 'implement', effort: 'codex53_high' },
+  debug:      { agent: 'debugger',       mcp: 'implement', effort: 'codex53_high' },
+  analyze:    { agent: 'analyst',        mcp: 'analyze',   effort: 'gpt54_xhigh' },
+  design:     { agent: 'architect',      mcp: 'analyze',   effort: 'gpt54_xhigh' },
+  review:     { agent: 'code-reviewer',  mcp: 'review',    effort: 'codex53_high' },
+  document:   { agent: 'writer',         mcp: 'docs',      effort: 'pro' },
+  research:   { agent: 'scientist',      mcp: 'analyze',   effort: 'codex53_high' },
+  'quick-fix':{ agent: 'build-fixer',    mcp: 'implement', effort: 'codex53_low' },
+  explain:    { agent: 'writer',         mcp: 'docs',      effort: 'flash' },
+  test:       { agent: 'test-engineer',  mcp: null,         effort: null },
+};
+
+/** @internal 키워드 → 카테고리 매핑 패턴 */
+const KEYWORD_PATTERNS = [
+  { category: 'implement', keywords: ['구현', '만들', '추가', '생성', '작성', '빌드', 'implement', 'create', 'add', 'build', 'make', 'develop'], weight: 1.0 },
+  { category: 'debug',     keywords: ['버그', '에러', '오류', '고쳐', '수정', '디버그', 'fix', 'bug', 'error', 'debug', 'troubleshoot', 'crash', 'broken'], weight: 1.0 },
+  { category: 'analyze',   keywords: ['분석', '조사', '파악', 'analyze', 'investigate', 'examine', 'inspect'], weight: 0.9 },
+  { category: 'design',    keywords: ['설계', '아키텍처', '디자인', '구조', 'design', 'architect', 'structure'], weight: 0.9 },
+  { category: 'review',    keywords: ['리뷰', '검토', '코드리뷰', 'review', 'code review', 'audit'], weight: 1.0 },
+  { category: 'document',  keywords: ['문서', '도큐먼트', '문서화', 'document', 'docs', 'documentation', 'readme'], weight: 0.9 },
+  { category: 'research',  keywords: ['리서치', '연구', '탐색', 'research', 'explore', 'study'], weight: 0.8 },
+  { category: 'quick-fix', keywords: ['빠르게', '간단히', '급한', 'quick fix', 'hotfix', 'quick'], weight: 0.85 },
+  { category: 'explain',   keywords: ['설명', '뭐야', '알려', '이해', 'explain', 'what is', 'how does', 'tell me', 'describe'], weight: 1.0 },
+  { category: 'test',      keywords: ['테스트', '테스팅', '시험', '검증', 'test', 'testing', 'spec', 'unit test'], weight: 1.0 },
+];
+
+/**
+ * 키워드 기반 빠른 분류 (0-cost, Codex 호출 없이)
+ * 고신뢰(>0.8) 시 Codex triage 건너뜀
+ * @param {string} prompt - 사용자 프롬프트
+ * @returns {{ category: string, confidence: number }}
+ */
+export function quickClassify(prompt) {
+  if (!prompt || typeof prompt !== 'string' || !prompt.trim()) {
+    return { category: 'implement', confidence: 0.1 };
+  }
+
+  const lower = prompt.toLowerCase().trim();
+  let bestCategory = null;
+  let bestScore = 0;
+  let bestMatchCount = 0;
+
+  for (const { category, keywords, weight } of KEYWORD_PATTERNS) {
+    let matchCount = 0;
+    for (const kw of keywords) {
+      if (lower.includes(kw)) matchCount++;
+    }
+    if (matchCount > 0) {
+      const score = (matchCount / keywords.length) * weight;
+      if (score > bestScore) {
+        bestScore = score;
+        bestCategory = category;
+        bestMatchCount = matchCount;
+      }
+    }
+  }
+
+  if (!bestCategory) {
+    return { category: 'implement', confidence: 0.3 };
+  }
+
+  // 매칭 품질 기반 신뢰도 (0.5~0.95 범위) — matchCount 기준으로 정규화 (3개 매칭이면 최대)
+  const confidence = Math.min(0.95, 0.5 + (Math.min(bestMatchCount, 3) / 3) * 0.45);
+  return { category: bestCategory, confidence };
+}
+
+/**
+ * 전체 의도 분류 — routing 정보 포함
+ * Codex triage 경로: codex 설치 시 실행, confidence > 0.8이면 즉시 반환
+ * quickClassify가 고신뢰(>0.8)이면 Codex 건너뜀
+ * 결과는 md5 해시 기반 Map에 5분 TTL로 캐싱
+ * @param {string} prompt
+ * @returns {{ category: string, confidence: number, reasoning: string, routing: { agent: string, mcp: string|null, effort: string|null } }}
+ */
+export function classifyIntent(prompt) {
+  const hash = _promptHash(String(prompt ?? ''));
+
+  // 캐시 확인
+  const cached = _getCached(hash);
+  if (cached) {
+    const routing = INTENT_CATEGORIES[cached.category] || INTENT_CATEGORIES.implement;
+    return {
+      category: cached.category,
+      confidence: cached.confidence,
+      reasoning: `cache-hit: ${cached.category} (${cached.confidence.toFixed(2)})`,
+      routing: { agent: routing.agent, mcp: routing.mcp, effort: routing.effort },
+    };
+  }
+
+  // quickClassify 먼저
+  const quick = quickClassify(prompt);
+
+  let category = quick.category;
+  let confidence = quick.confidence;
+  let reasoning;
+
+  // quickClassify가 고신뢰(>0.8)이면 Codex 건너뜀
+  if (quick.confidence > 0.8) {
+    reasoning = `keyword-match: ${category} (${confidence.toFixed(2)})`;
+  } else if (_isCodexAvailable()) {
+    // Codex triage
+    const codexResult = _tryCodexClassify(String(prompt ?? ''));
+    if (codexResult && codexResult.confidence > 0.8) {
+      category = codexResult.category;
+      confidence = codexResult.confidence;
+      reasoning = `codex-triage: ${category} (${confidence.toFixed(2)})`;
+    } else {
+      reasoning = `keyword-match(codex-fallback): ${category} (${confidence.toFixed(2)})`;
+    }
+  } else {
+    reasoning = `keyword-match: ${category} (${confidence.toFixed(2)})`;
+  }
+
+  // 캐시 저장
+  _intentCache.set(hash, { category, confidence, ts: Date.now() });
+
+  const routing = INTENT_CATEGORIES[category] || INTENT_CATEGORIES.implement;
+  return {
+    category,
+    confidence,
+    reasoning,
+    routing: { agent: routing.agent, mcp: routing.mcp, effort: routing.effort },
+  };
+}
+
+/**
+ * 분류 히스토리 기반 학습 (reflexion 연동 가능)
+ * @param {string} prompt
+ * @param {string} actualCategory - 실제 카테고리
+ */
+export function refineClassification(prompt, actualCategory) {
+  // reflexion 연동 시 store에 오분류 기록 저장 예정
+  void prompt;
+  void actualCategory;
+}