@triflux/core 10.50.1 → 10.51.0

package/hub/routing/q-learning.mjs

@@ -1,387 +0,0 @@
-// hub/routing/q-learning.mjs — 테이블 기반 Q-Learning 동적 라우팅
-// agent-map.json 폴백을 유지하면서, 작업 결과 피드백으로 가중치를 학습한다.
-// 외부 의존성 없음 (fs, path, crypto만 사용)
-
-import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { createRequire } from "node:module";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { scoreComplexity } from "./complexity.mjs";
-
-const _require = createRequire(import.meta.url);
-
-/** agent-map.json 정적 매핑 (폴백용) */
-let AGENT_MAP;
-try {
-  AGENT_MAP = _require("../team/agent-map.json");
-} catch {
-  AGENT_MAP = {};
-}
-
-/** 사용 가능한 CLI 액션 */
-const ACTIONS = ["codex", "antigravity", "claude", "haiku", "sonnet"];
-
-/** 특성 벡터 키워드 (48차원, 에이전트 타입 기반) */
-const FEATURE_KEYWORDS = [
-  // 실행/구현 (codex 친화)
-  "implement",
-  "execute",
-  "build",
-  "fix",
-  "debug",
-  "code",
-  "refactor",
-  "test",
-  // 분석/설계 (claude/sonnet 친화)
-  "analyze",
-  "architect",
-  "plan",
-  "review",
-  "security",
-  "optimize",
-  "research",
-  "evaluate",
-  // 디자인/문서 (Antigravity 친화)
-  "design",
-  "ui",
-  "ux",
-  "frontend",
-  "visual",
-  "document",
-  "write",
-  "explain",
-  // 간단/빠른 (haiku 친화)
-  "simple",
-  "quick",
-  "trivial",
-  "rename",
-  "format",
-  "lint",
-  "typo",
-  "minor",
-  // 한국어 — 실행/구현 (codex 친화)
-  "구현",
-  "빌드",
-  "수정",
-  "디버깅",
-  "리팩터링",
-  "테스트",
-  // 한국어 — 분석/설계 (claude/sonnet 친화)
-  "분석",
-  "아키텍처",
-  "설계",
-  "검토",
-  "보안",
-  "최적화",
-  // 한국어 — 디자인/문서 (Antigravity 친화)
-  "디자인",
-  "문서화",
-  // 한국어 — 간단/빠른 (haiku 친화)
-  "간단",
-  "사소한",
-];
-
-/**
- * 텍스트에서 48차원 특성 벡터 추출
- * 단어 경계를 기준으로 매칭하여 부분 문자열 오탐을 방지한다.
- * @param {string} text
- * @returns {number[]} 48-dim binary feature vector
- */
-function extractFeatures(text) {
-  const lower = text.toLowerCase();
-  return FEATURE_KEYWORDS.map((kw) => {
-    // 영문 단일 단어: 단어 경계(\b) 적용
-    // 한국어 또는 다중 단어 구문: 공백/문장 경계 기반 포함 여부 확인
-    if (/^[a-z]+$/.test(kw)) {
-      return new RegExp(`\\b${kw}\\b`).test(lower) ? 1 : 0;
-    }
-    return lower.includes(kw) ? 1 : 0;
-  });
-}
-
-/**
- * 특성 벡터를 상태 키로 변환 (해시 기반)
- * @param {number[]} features
- * @returns {string}
- */
-function stateKey(features) {
-  const hash = createHash("sha256").update(features.join(",")).digest("hex");
-  return hash.slice(0, 16);
-}
-
-/**
- * LRU 캐시 (예측 결과 캐싱)
- */
-class LRUCache {
-  /** @param {number} maxSize @param {number} ttlMs */
-  constructor(maxSize = 256, ttlMs = 5 * 60 * 1000) {
-    this._maxSize = maxSize;
-    this._ttlMs = ttlMs;
-    /** @type {Map<string, { value: *, ts: number }>} */
-    this._cache = new Map();
-  }
-
-  get(key) {
-    const entry = this._cache.get(key);
-    if (!entry) return undefined;
-    if (Date.now() - entry.ts > this._ttlMs) {
-      this._cache.delete(key);
-      return undefined;
-    }
-    // LRU: 다시 삽입하여 순서 갱신
-    this._cache.delete(key);
-    this._cache.set(key, entry);
-    return entry.value;
-  }
-
-  set(key, value) {
-    if (this._cache.has(key)) this._cache.delete(key);
-    this._cache.set(key, { value, ts: Date.now() });
-    // 초과 시 가장 오래된 항목 제거
-    if (this._cache.size > this._maxSize) {
-      const oldest = this._cache.keys().next().value;
-      this._cache.delete(oldest);
-    }
-  }
-
-  clear() {
-    this._cache.clear();
-  }
-}
-
-/**
- * Q-Learning 라우터
- * 테이블 기반 Q-Learning으로 작업→CLI 매핑을 학습한다.
- */
-export class QLearningRouter {
-  /**
-   * @param {object} [opts]
-   * @param {number} [opts.learningRate=0.1] — 학습률 (alpha)
-   * @param {number} [opts.discountFactor=0.9] — 할인율 (gamma)
-   * @param {number} [opts.epsilon=0.3] — 탐색 확률 (epsilon-greedy)
-   * @param {number} [opts.epsilonDecay=0.995] — 엡실론 감쇠율
-   * @param {number} [opts.epsilonMin=0.05] — 최소 엡실론
-   * @param {number} [opts.minConfidence=0.6] — 최소 신뢰도 (이하면 폴백)
-   * @param {string} [opts.modelPath] — Q-table 영속화 경로
-   * @param {() => number} [opts.random=Math.random] — 테스트/재현용 RNG seam
-   */
-  constructor(opts = {}) {
-    this._lr = opts.learningRate ?? 0.1;
-    this._gamma = opts.discountFactor ?? 0.9;
-    this._epsilon = opts.epsilon ?? 0.3;
-    this._epsilonDecay = opts.epsilonDecay ?? 0.995;
-    // epsilon=0 시에도 최소 탐색 보장 (pure-exploit 방지)
-    this._epsilonMin =
-      opts.epsilonMin ?? Math.max(0.01, Math.min(0.05, this._epsilon));
-    this._minConfidence = opts.minConfidence ?? 0.6;
-    this._modelPath =
-      opts.modelPath ?? join(homedir(), ".omc", "routing-model.json");
-    this._random =
-      typeof opts.random === "function" ? opts.random : Math.random;
-
-    /** @type {Map<string, Map<string, number>>} state -> (action -> Q-value) */
-    this._qTable = new Map();
-
-    /** @type {Map<string, number>} state -> visit count */
-    this._visitCounts = new Map();
-
-    /** 총 업데이트 횟수 */
-    this._totalUpdates = 0;
-
-    /** 예측 캐시 */
-    this._cache = new LRUCache(256, 5 * 60 * 1000);
-  }
-
-  /**
-   * 상태에 대한 Q-values 조회 (없으면 초기화)
-   * @param {string} state
-   * @returns {Map<string, number>}
-   */
-  _getQValues(state) {
-    if (!this._qTable.has(state)) {
-      const qValues = new Map();
-      for (const action of ACTIONS) {
-        qValues.set(action, 0);
-      }
-      this._qTable.set(state, qValues);
-    }
-    return this._qTable.get(state);
-  }
-
-  /**
-   * 작업 설명으로부터 최적 CLI 타입 예측
-   * @param {string} taskDescription
-   * @returns {{ action: string, confidence: number, exploration: boolean, complexity: number }}
-   */
-  predict(taskDescription) {
-    const features = extractFeatures(taskDescription);
-    const state = stateKey(features);
-
-    // 캐시 확인
-    const cached = this._cache.get(state);
-    if (cached) return cached;
-
-    const qValues = this._getQValues(state);
-    const visits = this._visitCounts.get(state) || 0;
-
-    // 엡실론-그리디: 탐색 vs 활용
-    const isExploration = this._random() < this._epsilon;
-
-    let action;
-    if (isExploration) {
-      // 무작위 탐색
-      action = ACTIONS[Math.floor(this._random() * ACTIONS.length)];
-    } else {
-      // 최적 액션 선택 (최대 Q-value)
-      let maxQ = -Infinity;
-      action = ACTIONS[0];
-      for (const [a, q] of qValues) {
-        if (q > maxQ) {
-          maxQ = q;
-          action = a;
-        }
-      }
-    }
-
-    // 신뢰도 계산: 방문 횟수 기반 (최소 10회 이상이면 안정)
-    const confidence = visits >= 10 ? Math.min(visits / 50, 1) : visits / 10;
-
-    const { score: complexity } = scoreComplexity(taskDescription);
-
-    const result = {
-      action,
-      confidence,
-      exploration: isExploration,
-      complexity,
-    };
-    // 탐색(랜덤) 결과는 캐싱하지 않음 — 매번 새로운 랜덤 액션 생성
-    if (!isExploration) this._cache.set(state, result);
-    return result;
-  }
-
-  /**
-   * Q-table 업데이트 (보상 피드백)
-   * @param {string} taskDescription — 작업 설명
-   * @param {string} action — 수행한 액션 (CLI 타입)
-   * @param {number} reward — 보상 (-1 ~ 1)
-   */
-  update(taskDescription, action, reward) {
-    if (!ACTIONS.includes(action)) return;
-
-    const features = extractFeatures(taskDescription);
-    const state = stateKey(features);
-    const qValues = this._getQValues(state);
-    const oldQ = qValues.get(action) || 0;
-
-    // 최대 미래 Q-value (단일 상태이므로 현재 상태의 max)
-    let maxFutureQ = -Infinity;
-    for (const [, q] of qValues) {
-      if (q > maxFutureQ) maxFutureQ = q;
-    }
-
-    // Q-Learning 업데이트: Q(s,a) = Q(s,a) + lr * (reward + gamma * max_Q(s') - Q(s,a))
-    const newQ = oldQ + this._lr * (reward + this._gamma * maxFutureQ - oldQ);
-    qValues.set(action, newQ);
-
-    // 방문 횟수 증가
-    this._visitCounts.set(state, (this._visitCounts.get(state) || 0) + 1);
-    this._totalUpdates++;
-
-    // 엡실론 감쇠
-    this._epsilon = Math.max(
-      this._epsilonMin,
-      this._epsilon * this._epsilonDecay,
-    );
-
-    // 캐시 무효화 (해당 상태)
-    this._cache.clear();
-  }
-
-  /**
-   * Q-table을 JSON 파일로 영속화
-   */
-  save() {
-    const dir = join(this._modelPath, "..");
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-
-    const data = {
-      version: 1,
-      epsilon: this._epsilon,
-      totalUpdates: this._totalUpdates,
-      qTable: {},
-      visitCounts: {},
-    };
-
-    for (const [state, qValues] of this._qTable) {
-      data.qTable[state] = Object.fromEntries(qValues);
-    }
-    for (const [state, count] of this._visitCounts) {
-      data.visitCounts[state] = count;
-    }
-
-    writeFileSync(this._modelPath, JSON.stringify(data, null, 2), "utf8");
-  }
-
-  /**
-   * 영속화된 Q-table 로드
-   * @returns {boolean} 로드 성공 여부
-   */
-  load() {
-    if (!existsSync(this._modelPath)) return false;
-
-    try {
-      const raw = readFileSync(this._modelPath, "utf8");
-      const data = JSON.parse(raw);
-      if (data.version !== 1) return false;
-
-      this._epsilon = data.epsilon ?? this._epsilon;
-      this._totalUpdates = data.totalUpdates ?? 0;
-      this._qTable = new Map();
-      this._visitCounts = new Map();
-
-      for (const [state, qObj] of Object.entries(data.qTable || {})) {
-        const qValues = new Map();
-        for (const [action, q] of Object.entries(qObj)) {
-          if (ACTIONS.includes(action)) qValues.set(action, q);
-        }
-        this._qTable.set(state, qValues);
-      }
-      for (const [state, count] of Object.entries(data.visitCounts || {})) {
-        this._visitCounts.set(state, count);
-      }
-
-      this._cache.clear();
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * agent-map.json 폴백 조회
-   * @param {string} agentType — 에이전트 역할명
-   * @returns {string} CLI 타입
-   */
-  static fallback(agentType) {
-    return AGENT_MAP[agentType] || agentType;
-  }
-
-  /** 현재 엡실론 값 */
-  get epsilon() {
-    return this._epsilon;
-  }
-
-  /** 총 업데이트 횟수 */
-  get totalUpdates() {
-    return this._totalUpdates;
-  }
-
-  /** Q-table 상태 수 */
-  get stateCount() {
-    return this._qTable.size;
-  }
-}
-
-// 모듈 레벨 export
-export { ACTIONS, extractFeatures, FEATURE_KEYWORDS, LRUCache, stateKey };

package/hub/routing-snapshot.mjs

@@ -1,261 +0,0 @@
-// hub/routing-snapshot.mjs
-//
-// PRD: .omx/plans/prd-dynamic-routing-engine.md
-//
-// Phase 0 — pure read-only context projector. Wraps HUD providers and the
-// AccountBroker public snapshot into a single deterministic snapshot that
-// `evaluateDynamicRoute(request, snapshot, policy)` consumes.
-//
-// Phase 0 contract:
-//   - no callers yet (dormant). Only `evaluateDynamicRoute()` is meant to read this.
-//   - lazy import of HUD providers + broker so this module imports cleanly even
-//     when those surfaces are absent in tests.
-//   - never mutates upstream state — strictly read-only.
-//   - all output fields are derivable from `publicSnapshot()` / HUD redacted API,
-//     so writing the resulting snapshot to disk does not leak credentials.
-
-const CLAUDE_HUD_MODULE = "../hud/providers/claude.mjs";
-const CODEX_HUD_MODULE = "../hud/providers/codex.mjs";
-const BROKER_MODULE = "./account-broker.mjs";
-
-async function loadHudClaude() {
-  try {
-    return await import(CLAUDE_HUD_MODULE);
-  } catch {
-    return null;
-  }
-}
-
-async function loadHudCodex() {
-  try {
-    return await import(CODEX_HUD_MODULE);
-  } catch {
-    return null;
-  }
-}
-
-async function loadBroker() {
-  try {
-    const mod = await import(BROKER_MODULE);
-    return mod.broker ?? mod.default ?? null;
-  } catch {
-    return null;
-  }
-}
-
-function normalizeClaudeUsage(raw, now) {
-  if (!raw || typeof raw !== "object") return null;
-  const data = raw.data ?? raw;
-  if (!data) return null;
-  return {
-    fiveHourPercent: numericOrNull(data.fiveHourPercent),
-    weeklyPercent: numericOrNull(data.weeklyPercent),
-    fiveHourResetsAt: toEpoch(data.fiveHourResetsAt),
-    weeklyResetsAt: toEpoch(data.weeklyResetsAt),
-    observedAt: toEpoch(data.observedAt) ?? now,
-    isStale: Boolean(raw.isStale ?? data.isStale),
-    source: data.source ?? "hud/providers/claude.mjs",
-  };
-}
-
-function normalizeCodexUsage(raw, now) {
-  if (!raw || typeof raw !== "object") return null;
-  const buckets = raw.buckets ?? raw.data?.buckets ?? raw;
-  if (!buckets || typeof buckets !== "object") return null;
-  const entries = Object.entries(buckets);
-  if (entries.length === 0) return null;
-  const out = {};
-  for (const [id, bucket] of entries) {
-    if (!bucket || typeof bucket !== "object") continue;
-    out[id] = {
-      primary: normalizeCodexBucketLeg(bucket.primary),
-      secondary: normalizeCodexBucketLeg(bucket.secondary),
-    };
-  }
-  return {
-    buckets: out,
-    observedAt: toEpoch(raw.observedAt) ?? now,
-    isStale: Boolean(raw.shouldRefresh === false ? false : raw.isStale),
-    source: raw.source ?? "hud/providers/codex.mjs",
-  };
-}
-
-function normalizeCodexBucketLeg(leg) {
-  if (!leg || typeof leg !== "object") return null;
-  return {
-    usedPercent: numericOrNull(leg.used_percent ?? leg.usedPercent),
-    resetsAt: toEpoch(leg.resets_at ?? leg.resetsAt),
-  };
-}
-
-function normalizeBrokerSnapshot(raw) {
-  if (!Array.isArray(raw)) return null;
-  const grouped = { codex: [], claude: [], gemini: [] };
-  for (const entry of raw) {
-    if (!entry || typeof entry !== "object") continue;
-    const provider = entry.provider;
-    if (!grouped[provider]) continue;
-    grouped[provider].push({
-      id: entry.id,
-      tier: entry.tier ?? "unknown",
-      busy: Boolean(entry.busy),
-      cooldownUntil: toEpoch(entry.cooldownUntil),
-      lastUsedAt: toEpoch(entry.lastUsedAt),
-      remainingMs: numericOrNull(entry.remainingMs),
-      circuitState: entry.circuitState ?? "closed",
-      failureCount: numericOrNull(entry.failureCount) ?? 0,
-      expiresAt: toEpoch(entry.expiresAt),
-      drainAfter: toEpoch(entry.drainAfter),
-    });
-  }
-  return grouped;
-}
-
-function numericOrNull(v) {
-  if (v === null || v === undefined) return null;
-  const n = Number(v);
-  return Number.isFinite(n) ? n : null;
-}
-
-function toEpoch(v) {
-  if (v === null || v === undefined) return null;
-  if (typeof v === "number") return Number.isFinite(v) ? v : null;
-  const parsed = Date.parse(v);
-  return Number.isNaN(parsed) ? null : parsed;
-}
-
-export async function buildRoutingSnapshot({
-  forceRefresh = false,
-  now = Date.now(),
-} = {}) {
-  const [hudClaude, hudCodex, broker] = await Promise.all([
-    loadHudClaude(),
-    loadHudCodex(),
-    loadBroker(),
-  ]);
-
-  let claude = null;
-  if (hudClaude?.readClaudeUsageSnapshot) {
-    try {
-      claude = normalizeClaudeUsage(
-        hudClaude.readClaudeUsageSnapshot({ forceRefresh }),
-        now,
-      );
-    } catch (err) {
-      claude = {
-        error: String(err?.message ?? err),
-        observedAt: now,
-        isStale: true,
-      };
-    }
-  }
-
-  let codex = null;
-  if (hudCodex?.readCodexRateLimitSnapshot) {
-    try {
-      codex = normalizeCodexUsage(
-        hudCodex.readCodexRateLimitSnapshot({ forceRefresh }),
-        now,
-      );
-    } catch (err) {
-      codex = {
-        error: String(err?.message ?? err),
-        observedAt: now,
-        isStale: true,
-      };
-    }
-  }
-
-  let brokerState = null;
-  if (broker?.publicSnapshot) {
-    try {
-      brokerState = normalizeBrokerSnapshot(broker.publicSnapshot());
-    } catch (err) {
-      brokerState = { error: String(err?.message ?? err) };
-    }
-  }
-
-  return {
-    schemaVersion: 1,
-    observedAt: now,
-    claude,
-    codex,
-    broker: brokerState,
-  };
-}
-
-// Phase 1 — in-process snapshot cache.
-// 의도: caller (Phase 1+ conductor / swarm-hypervisor) 가 spawn loop 에서
-// 매번 HUD/broker IO 를 트리거하지 않도록 정해진 TTL 안에서 같은 snapshot
-// 을 재사용한다. cache 는 모듈-local 이라 process 단위 (테스트 격리 위해
-// `resetSnapshotCache()` 노출).
-
-const DEFAULT_CACHE_TTL_MS = 900_000; // policy freshness max 와 정합
-
-let _cache = null; // { snapshot, fetchedAt }
-
-export function resetSnapshotCache() {
-  _cache = null;
-}
-
-/**
- * Cached snapshot shortcut. cache TTL 안이면 재사용, 아니면 새로 빌드.
- *
- * @param {{
- *   forceRefresh?: boolean,        // true 면 cache 무시하고 새로 빌드
- *   maxAgeMs?: number,             // override cache TTL (default 900_000)
- *   now?: number,                  // pure-fn: caller 가 epoch 주입 (default Date.now())
- *   builder?: function,            // 테스트용 builder 주입 (default buildRoutingSnapshot)
- * }} [opts]
- * @returns {Promise<object>}
- */
-export async function getDefaultSnapshot(opts = {}) {
-  const now = typeof opts.now === "number" ? opts.now : Date.now();
-  const maxAgeMs =
-    typeof opts.maxAgeMs === "number" ? opts.maxAgeMs : DEFAULT_CACHE_TTL_MS;
-  const builder = opts.builder || buildRoutingSnapshot;
-  const forceRefresh = Boolean(opts.forceRefresh);
-
-  if (!forceRefresh && _cache && now - _cache.fetchedAt < maxAgeMs) {
-    return _cache.snapshot;
-  }
-
-  const snapshot = await builder({ forceRefresh, now });
-  _cache = { snapshot, fetchedAt: now };
-  return snapshot;
-}
-
-/**
- * Synchronous cache shortcut. cache TTL 안에 fresh snapshot이 있으면 즉시 반환,
- * 아니면 null. caller (sync hot path — e.g. conductor.spawnSession) 가 broker.lease
- * atomic 인변량을 깨지 않고 dynamic routing decision 을 sync 로 평가할 수 있도록 한다.
- * builder 호출(IO)은 하지 않는다 — cache miss 면 caller 가 fallback decision 사용.
- *
- * @param {{
- *   maxAgeMs?: number,             // override cache TTL (default 900_000)
- *   now?: number,                  // pure-fn: caller 가 epoch 주입 (default Date.now())
- * }} [opts]
- * @returns {object|null} cache fresh이면 snapshot, 아니면 null
- */
-export function tryGetCachedSnapshot(opts = {}) {
-  const now = typeof opts.now === "number" ? opts.now : Date.now();
-  const maxAgeMs =
-    typeof opts.maxAgeMs === "number" ? opts.maxAgeMs : DEFAULT_CACHE_TTL_MS;
-  if (_cache && now - _cache.fetchedAt < maxAgeMs) {
-    return _cache.snapshot;
-  }
-  return null;
-}
-
-// Test helpers — pure normalizers exposed so unit tests can build snapshots
-// from mock provider responses without running real HUD I/O.
-export const __internal__ = {
-  normalizeClaudeUsage,
-  normalizeCodexUsage,
-  normalizeBrokerSnapshot,
-  // Phase 1 cache 테스트 helpers
-  getCacheStateForTest: () => (_cache ? { ..._cache } : null),
-  setCacheForTest: (state) => {
-    _cache = state ? { ...state } : null;
-  },
-};