@triflux/core 10.0.0-alpha.1

package/hub/reflexion.mjs

@@ -0,0 +1,372 @@
+// hub/reflexion.mjs — Cross-Session Error Learning Engine
+// 에러를 구조화 저장 → 다음 세션에서 유사 에러 패턴 매칭 → 자동 솔루션 적용
+
+const DEFAULT_REFLEXION_TYPE = "reflexion";
+export const ADAPTIVE_RULE_TYPE = "adaptive";
+const DEFAULT_CONFIDENCE = 0.5;
+const ACTIVE_RULE_CONFIDENCE = 0.5;
+const ADAPTIVE_PROMOTION_STEP = 0.1;
+const ADAPTIVE_DECAY_STEP = 0.1;
+const ADAPTIVE_DECAY_WINDOW = 5;
+const ADAPTIVE_DELETE_THRESHOLD = 0.3;
+
+function clampConfidence(value) {
+  const next = Number(value);
+  if (!Number.isFinite(next)) return DEFAULT_CONFIDENCE;
+  return Math.max(0, Math.min(1, next));
+}
+
+function safeJson(value) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return "";
+  }
+}
+
+function pickString(...values) {
+  return (
+    values.find((value) => typeof value === "string" && value.trim())?.trim() ||
+    ""
+  );
+}
+
+function pickSessionCount(...values) {
+  const raw = values.find((value) => Number.isFinite(Number(value)));
+  return raw == null ? 0 : Math.max(0, Math.trunc(Number(raw)));
+}
+
+function pickSessionId(errorContext = {}) {
+  return pickString(
+    errorContext.session_id,
+    errorContext.sessionId,
+    errorContext.context?.session_id,
+    errorContext.context?.sessionId,
+  );
+}
+
+function pickProjectSlug(errorContext = {}) {
+  return pickString(
+    errorContext.projectSlug,
+    errorContext.project_slug,
+    errorContext.context?.projectSlug,
+    errorContext.context?.project_slug,
+  );
+}
+
+function compactObject(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, entry]) => entry != null && entry !== ""),
+  );
+}
+
+function buildErrorText(errorContext = {}) {
+  const parts = [
+    pickString(errorContext.tool_output),
+    pickString(errorContext.error),
+    pickString(errorContext.tool_input?.command),
+    errorContext.tool_result == null ? "" : safeJson(errorContext.tool_result),
+  ].filter(Boolean);
+  return parts.join("\n").trim();
+}
+
+function buildAdaptiveContext(errorContext = {}) {
+  return compactObject({
+    source: "PostToolUseFailure",
+    tool_name: pickString(errorContext.tool_name),
+    agent: pickString(errorContext.agent, errorContext.context?.agent),
+    cli: pickString(errorContext.cli, errorContext.context?.cli),
+    command: pickString(errorContext.tool_input?.command),
+    file: pickString(
+      errorContext.tool_input?.file_path,
+      errorContext.context?.file,
+    ),
+    project_slug: pickProjectSlug(errorContext),
+  });
+}
+
+function buildAdaptiveSolution(errorContext = {}, errorText = "") {
+  const explicit = pickString(
+    errorContext.systemMessage,
+    errorContext.additionalContext,
+    errorContext.hint,
+  );
+  if (explicit) return explicit;
+  const toolName = pickString(errorContext.tool_name) || "tool";
+  const command = pickString(errorContext.tool_input?.command);
+  const summary = errorText.split("\n")[0]?.trim() || "반복 실패 패턴";
+  if (command)
+    return `${toolName} 재시도 전 입력을 검증하세요: ${command}\n원인: ${summary}`;
+  return `${toolName} 재시도 전 실패 원인을 검증하세요: ${summary}`;
+}
+
+function normalizeSessionIds(sessionIds) {
+  if (!Array.isArray(sessionIds)) return [];
+  return [
+    ...new Set(
+      sessionIds.filter((value) => typeof value === "string" && value.trim()),
+    ),
+  ];
+}
+
+function getAdaptiveState(rule = {}) {
+  const state = rule.adaptive_state || {};
+  const session_ids = normalizeSessionIds(state.session_ids);
+  return {
+    ...state,
+    project_slug: pickString(state.project_slug, rule.context?.project_slug),
+    session_ids,
+    session_occurrences: Math.max(
+      state.session_occurrences || 0,
+      session_ids.length,
+    ),
+    last_seen_session: pickSessionCount(state.last_seen_session),
+    last_decay_session: pickSessionCount(state.last_decay_session),
+  };
+}
+
+function mergeAdaptiveState(rule, errorContext = {}) {
+  const current = getAdaptiveState(rule);
+  const sessionId = pickSessionId(errorContext);
+  const sessionCount = pickSessionCount(
+    errorContext.sessionCount,
+    errorContext.session_count,
+    errorContext.context?.sessionCount,
+    errorContext.context?.session_count,
+  );
+  const session_ids = normalizeSessionIds(
+    sessionId ? [...current.session_ids, sessionId] : current.session_ids,
+  );
+  return {
+    ...current,
+    project_slug: pickString(
+      pickProjectSlug(errorContext),
+      current.project_slug,
+    ),
+    session_ids,
+    session_occurrences: Math.max(
+      current.session_occurrences,
+      session_ids.length,
+    ),
+    last_seen_session: Math.max(current.last_seen_session, sessionCount),
+    last_decay_session: current.last_decay_session || sessionCount,
+  };
+}
+
+function filterEntriesByType(entries, type) {
+  return entries.filter(
+    (entry) => (entry.type || DEFAULT_REFLEXION_TYPE) === type,
+  );
+}
+
+/**
+ * 에러 메시지를 정규화된 패턴 시그니처로 변환
+ * 파일 경로, 줄 번호, 타임스탬프, UUID, 숫자 리터럴을 플레이스홀더로 치환
+ * @param {string} errorMessage
+ * @returns {string}
+ */
+export function normalizeError(errorMessage) {
+  if (!errorMessage || typeof errorMessage !== "string") return "";
+  let p = errorMessage;
+  p = p.replace(/[A-Za-z]:\\[\w\\.\-/]+/g, "<FILE>");
+  p = p.replace(/(?:\/[\w.-]+){2,}/g, "<FILE>");
+  p = p.replace(/:(\d+)(:\d+)?(?=[\s,)\]]|$)/g, ":<LINE>");
+  p = p.replace(/\b[Ll]ine\s+\d+/g, "line <LINE>");
+  p = p.replace(/\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}[\w.+-]*/g, "<TIME>");
+  p = p.replace(
+    /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi,
+    "<ID>",
+  );
+  p = p.replace(/\b[0-9a-f]{32,}\b/gi, "<ID>");
+  p = p.replace(/\b\d{10,13}\b/g, "<TIME>");
+  p = p.replace(/\b\d{4,}\b/g, "<NUM>");
+  return p.toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+/**
+ * 에러에 대한 기존 솔루션 검색
+ * @param {object} store - createStore() 반환 객체
+ * @param {string} errorMessage - 원본 에러 메시지
+ * @param {object} [context={}] - { file, function, cli, agent }
+ * @returns {{ found: boolean, entries: Array, bestMatch: object|null }}
+ */
+export function lookupSolution(store, errorMessage, context = {}) {
+  const pattern = normalizeError(errorMessage);
+  if (!pattern) return { found: false, entries: [], bestMatch: null };
+  const entries = store.findReflexion(pattern, context);
+  if (!entries.length) return { found: false, entries: [], bestMatch: null };
+  return { found: true, entries, bestMatch: entries[0] };
+}
+
+/**
+ * 에러 해결 후 학습 저장
+ * 동일 패턴이 존재하면 hit 업데이트, 없으면 새로 생성
+ * @param {object} store
+ * @param {{ error: string, solution: string, context?: object, success?: boolean }} opts
+ * @returns {object|null}
+ */
+export function learnFromError(
+  store,
+  { error, solution, context = {}, success = false },
+) {
+  const pattern = normalizeError(error);
+  if (!pattern || !solution) return null;
+  const existing = filterEntriesByType(
+    store.findReflexion(pattern, context),
+    DEFAULT_REFLEXION_TYPE,
+  );
+  if (existing.length && existing[0].error_pattern === pattern) {
+    return store.updateReflexionHit(existing[0].id, success);
+  }
+  const newEntry = store.addReflexion({
+    type: DEFAULT_REFLEXION_TYPE,
+    error_pattern: pattern,
+    error_message: error,
+    context,
+    solution,
+    solution_code: null,
+  });
+  return success && newEntry
+    ? store.updateReflexionHit(newEntry.id, true)
+    : newEntry;
+}
+
+/**
+ * 솔루션 적용 결과 피드백
+ * @param {object} store
+ * @param {string} entryId
+ * @param {boolean} success
+ * @returns {object|null}
+ */
+export function reportOutcome(store, entryId, success) {
+  return store.updateReflexionHit(entryId, success);
+}
+
+/**
+ * PostToolUseFailure 컨텍스트에서 adaptive rule payload 생성
+ * @param {object} errorContext
+ * @returns {object|null}
+ */
+export function adaptiveRuleFromError(errorContext = {}) {
+  const errorText = buildErrorText(errorContext);
+  const pattern = normalizeError(errorText);
+  if (!pattern) return null;
+  return {
+    type: ADAPTIVE_RULE_TYPE,
+    error_pattern: pattern,
+    error_message: errorText,
+    context: buildAdaptiveContext(errorContext),
+    solution: buildAdaptiveSolution(errorContext, errorText),
+    solution_code: null,
+    adaptive_state: (() => {
+      const sessionId = pickSessionId(errorContext);
+      const sessionCount = pickSessionCount(
+        errorContext.sessionCount,
+        errorContext.session_count,
+      );
+      return {
+        project_slug: pickProjectSlug(errorContext),
+        session_ids: sessionId ? [sessionId] : [],
+        session_occurrences: sessionId ? 1 : 0,
+        last_seen_session: sessionCount,
+        last_decay_session: sessionCount,
+      };
+    })(),
+    confidence: DEFAULT_CONFIDENCE,
+    hit_count: 1,
+    success_count: 0,
+  };
+}
+
+/**
+ * 동일 패턴이 여러 세션에서 재발하면 adaptive rule confidence를 승격
+ * @param {object} store
+ * @param {string} ruleId
+ * @param {object} [errorContext={}]
+ * @returns {object|null}
+ */
+export function promoteRule(store, ruleId, errorContext = {}) {
+  const rule = store.getReflexion(ruleId);
+  if (!rule || rule.type !== ADAPTIVE_RULE_TYPE || !store.patchReflexion)
+    return null;
+  const current = getAdaptiveState(rule);
+  const next = mergeAdaptiveState(rule, errorContext);
+  const newSession = next.session_occurrences > current.session_occurrences;
+  const promoted =
+    newSession && next.session_occurrences >= 2
+      ? clampConfidence(rule.confidence + ADAPTIVE_PROMOTION_STEP)
+      : rule.confidence;
+  return store.patchReflexion(ruleId, {
+    adaptive_state: next,
+    confidence: promoted,
+    hit_count: (rule.hit_count || 0) + 1,
+    last_hit_ms: Date.now(),
+  });
+}
+
+/**
+ * 지정 세션 수만큼 관측되지 않은 adaptive rules confidence 감소
+ * @param {object} store
+ * @param {number} sessionCount
+ * @returns {{ updated: Array, deleted: string[] }}
+ */
+export function decayRules(store, sessionCount) {
+  const currentSession = pickSessionCount(sessionCount);
+  if (!store.listReflexion || !store.patchReflexion || !store.deleteReflexion) {
+    return { updated: [], deleted: [] };
+  }
+  const result = { updated: [], deleted: [] };
+  for (const rule of store.listReflexion({ type: ADAPTIVE_RULE_TYPE })) {
+    const state = getAdaptiveState(rule);
+    const baseline = Math.max(
+      state.last_seen_session,
+      state.last_decay_session,
+    );
+    const decaySteps = Math.floor(
+      (currentSession - baseline) / ADAPTIVE_DECAY_WINDOW,
+    );
+    if (decaySteps <= 0) continue;
+    const confidence = clampConfidence(
+      rule.confidence - decaySteps * ADAPTIVE_DECAY_STEP,
+    );
+    if (confidence <= ADAPTIVE_DELETE_THRESHOLD) {
+      if (store.deleteReflexion(rule.id)) result.deleted.push(rule.id);
+      continue;
+    }
+    const updated = store.patchReflexion(rule.id, {
+      confidence,
+      adaptive_state: {
+        ...state,
+        last_decay_session: baseline + decaySteps * ADAPTIVE_DECAY_WINDOW,
+      },
+    });
+    if (updated) result.updated.push(updated);
+  }
+  return result;
+}
+
+/**
+ * 현재 활성화된 adaptive rules 조회
+ * @param {object} store
+ * @param {string} projectSlug
+ * @returns {Array}
+ */
+export function getActiveAdaptiveRules(store, projectSlug) {
+  if (!store.listReflexion) return [];
+  return store
+    .listReflexion({ type: ADAPTIVE_RULE_TYPE, projectSlug })
+    .filter((rule) => rule.confidence > ACTIVE_RULE_CONFIDENCE);
+}
+
+/**
+ * 신뢰도 자동 조정 (success_count / hit_count, 샘플 크기 기반 감쇠)
+ * hit_count가 작으면 0.5(기본값)쪽으로 보수적으로 수렴
+ * @param {object} entry - { hit_count, success_count }
+ * @returns {number} 0~1 사이 신뢰도
+ */
+export function recalcConfidence(entry) {
+  if (!entry?.hit_count || entry.hit_count <= 0) return DEFAULT_CONFIDENCE;
+  const ratio = entry.success_count / entry.hit_count;
+  const decay = Math.min(1, entry.hit_count / 10);
+  return ratio * decay + DEFAULT_CONFIDENCE * (1 - decay);
+}

package/hub/research.mjs

@@ -0,0 +1,146 @@
+// hub/research.mjs — 자율 웹 리서치 엔진 코어
+// 검색 쿼리 생성 → 결과 정규화 → 보고서 빌드 → 저장
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { TFX_REPORTS_DIR } from './paths.mjs';
+
+/**
+ * 주제에서 검색 쿼리 3-5개를 자동 생성한다.
+ * 한국어 주제 → 한국어 + 영어 혼합, 영어 주제 → 영어 쿼리.
+ * @param {string} topic - 리서치 주제
+ * @param {'ko'|'en'|'auto'} [lang='auto'] - 언어 힌트
+ * @returns {string[]} 검색 쿼리 배열
+ */
+export function generateQueries(topic, lang = 'auto') {
+  if (!topic || typeof topic !== 'string' || !topic.trim()) return [];
+
+  const t = topic.trim();
+  const detectedLang = lang === 'auto' ? detectLang(t) : lang;
+
+  if (detectedLang === 'ko') {
+    return [
+      `${t} 정리`,
+      `${t} 비교 분석`,
+      `${t} 최신 동향 ${new Date().getFullYear()}`,
+      `${toEnglishQuery(t)} overview`,
+      `${toEnglishQuery(t)} comparison ${new Date().getFullYear()}`,
+    ];
+  }
+
+  return [
+    `${t} overview`,
+    `${t} comparison`,
+    `${t} best practices ${new Date().getFullYear()}`,
+    `${t} pros and cons`,
+  ];
+}
+
+/**
+ * 검색 원시 결과를 정규화한다. 중복 URL 제거 + 빈/null 필터링.
+ * @param {Array<object|null|undefined>} rawResults - 검색 엔진 원시 결과
+ * @returns {Array<{title: string, url: string, snippet: string}>}
+ */
+export function normalizeResults(rawResults) {
+  if (!Array.isArray(rawResults)) return [];
+
+  const seen = new Set();
+  const out = [];
+
+  for (const r of rawResults) {
+    if (!r || typeof r !== 'object') continue;
+    const url = (r.url || r.link || '').trim();
+    const title = (r.title || r.name || '').trim();
+    const snippet = (r.snippet || r.description || r.content || '').trim();
+
+    if (!url || seen.has(url)) continue;
+    seen.add(url);
+    out.push({ title, url, snippet });
+  }
+
+  return out;
+}
+
+/**
+ * 리서치 보고서를 마크다운으로 빌드한다.
+ * @param {string} topic - 리서치 주제
+ * @param {string[]} findings - 핵심 발견 목록
+ * @param {Array<{title: string, url: string, snippet: string}>} sources - 출처 목록
+ * @returns {string} 마크다운 문자열
+ */
+export function buildReport(topic, findings, sources) {
+  const date = new Date().toISOString().split('T')[0];
+  const findingsSection = (findings || [])
+    .map((f, i) => `${i + 1}. ${f}`)
+    .join('\n');
+  const sourcesSection = (sources || [])
+    .map((s) => `- [${s.title || s.url}](${s.url})${s.snippet ? ` — ${s.snippet}` : ''}`)
+    .join('\n');
+
+  return `# Research: ${topic}
+Date: ${date}
+
+## Executive Summary
+${topic}에 대한 자동 리서치 결과입니다.
+
+## Key Findings
+${findingsSection || '_발견 없음_'}
+
+## Actionable Recommendations
+리서치 결과를 바탕으로 다음 단계를 검토하세요.
+
+## Sources
+${sourcesSection || '_출처 없음_'}
+`;
+}
+
+/**
+ * 보고서를 .tfx/reports/research-{timestamp}.md에 저장한다.
+ * @param {string} topic - 리서치 주제 (파일명 생성용)
+ * @param {string} content - 마크다운 보고서 내용
+ * @param {string} [baseDir=process.cwd()] - 프로젝트 루트 경로
+ * @returns {string} 저장된 파일 경로
+ */
+export function saveReport(topic, content, baseDir = process.cwd()) {
+  const dir = join(baseDir, TFX_REPORTS_DIR);
+  const resolvedDir = resolve(dir);
+  const expectedBase = resolve(baseDir || TFX_REPORTS_DIR);
+  if (!resolvedDir.startsWith(expectedBase)) {
+    throw new Error('Invalid report directory: path traversal detected');
+  }
+  mkdirSync(dir, { recursive: true });
+
+  const ts = new Date().toISOString().replace(/[:.]/g, '-').replace('T', '_').slice(0, 19);
+  const slug = (topic || 'untitled')
+    .replace(/[^a-zA-Z0-9가-힣\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .slice(0, 40)
+    .toLowerCase();
+  const filename = `research-${ts}-${slug}.md`;
+  const filepath = join(dir, filename);
+
+  writeFileSync(filepath, content, 'utf-8');
+  return filepath;
+}
+
+// ── internal helpers ──
+
+/**
+ * 텍스트에 한글이 포함되어 있으면 'ko', 아니면 'en'
+ * @param {string} text
+ * @returns {'ko'|'en'}
+ */
+function detectLang(text) {
+  return /[가-힣]/.test(text) ? 'ko' : 'en';
+}
+
+/**
+ * 한국어 토픽에서 영어 검색 쿼리용 문자열 추출.
+ * 영문/숫자만 남기고, 없으면 원문 그대로 반환.
+ * @param {string} text
+ * @returns {string}
+ */
+function toEnglishQuery(text) {
+  const eng = text.replace(/[가-힣\s]+/g, ' ').trim();
+  return eng || text;
+}