@triflux/core 10.0.0-alpha.1

package/hub/cli-adapter-base.mjs

@@ -0,0 +1,192 @@
+// hub/cli-adapter-base.mjs — codex/gemini 공통 CLI adapter 인터페이스
+// Phase 2: codex-adapter.mjs에서 추출한 재사용 가능 유틸리티
+
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+
+import { killProcess, IS_WINDOWS } from './platform.mjs';
+
+// ── Shell utilities ─────────────────────────────────────────────
+
+export function normalizePathForShell(value) {
+  return IS_WINDOWS ? String(value).replace(/\\/g, '/') : String(value);
+}
+
+export function shellQuote(value) {
+  return JSON.stringify(String(value));
+}
+
+// ── Sleep ───────────────────────────────────────────────────────
+
+export function sleep(ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+  });
+}
+
+// ── Result factory ──────────────────────────────────────────────
+
+export function createResult(ok, extra = {}) {
+  return {
+    ok,
+    output: '',
+    stderr: '',
+    exitCode: null,
+    duration: 0,
+    retried: false,
+    fellBack: false,
+    failureMode: ok ? null : 'crash',
+    ...extra,
+  };
+}
+
+export function appendWarnings(stderr, warnings = []) {
+  const text = warnings.map((item) => `[preflight] ${item}`).join('\n');
+  return [stderr, text].filter(Boolean).join('\n');
+}
+
+// ── Circuit breaker factory ─────────────────────────────────────
+
+export function createCircuitBreaker(opts = {}) {
+  const state = {
+    failures: [],
+    maxFailures: opts.maxFailures ?? 3,
+    windowMs: opts.windowMs ?? 10 * 60_000,
+    openedAt: 0,
+    trialInFlight: false,
+  };
+
+  function pruneFailures(now = Date.now()) {
+    state.failures = state.failures.filter((stamp) => now - stamp < state.windowMs);
+  }
+
+  function reset() {
+    state.failures = [];
+    state.openedAt = 0;
+    state.trialInFlight = false;
+  }
+
+  function recordFailure(isHalfOpen, now = Date.now()) {
+    pruneFailures(now);
+    state.failures = [...state.failures, now];
+    state.trialInFlight = false;
+    if (isHalfOpen || state.failures.length >= state.maxFailures) {
+      state.openedAt = now;
+    }
+  }
+
+  function getState(now = Date.now()) {
+    pruneFailures(now);
+    const withinWindow = state.openedAt && now - state.openedAt < state.windowMs;
+    const current = withinWindow ? 'open' : (state.openedAt ? 'half-open' : 'closed');
+    return {
+      state: current,
+      failures: [...state.failures],
+      maxFailures: state.maxFailures,
+      windowMs: state.windowMs,
+      openedAt: state.openedAt || null,
+      trialInFlight: state.trialInFlight,
+    };
+  }
+
+  function canExecute() {
+    const circuit = getState();
+    if (circuit.state === 'open') return { allowed: false, halfOpen: false };
+    if (circuit.state === 'half-open' && state.trialInFlight) return { allowed: false, halfOpen: true };
+    const halfOpen = circuit.state === 'half-open';
+    if (halfOpen) state.trialInFlight = true;
+    return { allowed: true, halfOpen };
+  }
+
+  function clearTrial() {
+    state.trialInFlight = false;
+  }
+
+  return { getState, recordFailure, reset, canExecute, clearTrial };
+}
+
+// ── Process termination ─────────────────────────────────────────
+
+export async function terminateChild(pid, opts = {}) {
+  if (!pid) return;
+  const graceMs = opts.graceMs ?? 5000;
+  killProcess(pid, { signal: 'SIGTERM', tree: true, timeout: graceMs });
+  await sleep(graceMs);
+  killProcess(pid, { signal: 'SIGKILL', tree: true, force: true, timeout: graceMs });
+}
+
+// ── Process execution with stall detection ──────────────────────
+
+/**
+ * Spawn a CLI process with timeout + stall detection.
+ *
+ * @param {string} command — shell command to run
+ * @param {string} workdir — cwd for the child process
+ * @param {number} timeout — max duration in ms
+ * @param {object} [opts]
+ * @param {string} [opts.resultFile] — file to read output from (if CLI writes there)
+ * @param {function} [opts.inferStallMode] — (stdout, stderr) => string. Default: () => 'timeout'
+ * @param {number} [opts.stallCheckIntervalMs] — stall check interval (default 10_000)
+ * @param {number} [opts.stallThresholdMs] — stall threshold (default 30_000)
+ * @returns {Promise<object>} createResult-shaped object
+ */
+export async function runProcess(command, workdir, timeout, opts = {}) {
+  const startedAt = Date.now();
+  const inferStallMode = opts.inferStallMode || (() => 'timeout');
+  const stallCheckIntervalMs = opts.stallCheckIntervalMs ?? 10_000;
+  const stallThresholdMs = opts.stallThresholdMs ?? 30_000;
+  const resultFile = opts.resultFile || null;
+
+  let stdout = '';
+  let stderr = '';
+  let exitCode = null;
+  let failureMode = null;
+  let child;
+
+  try {
+    child = spawn(command, { cwd: workdir, shell: true, windowsHide: true });
+  } catch (error) {
+    return createResult(false, { stderr: String(error?.message || error), duration: Date.now() - startedAt });
+  }
+
+  let lastBytes = 0;
+  let lastChange = Date.now();
+  const touch = () => { lastChange = Date.now(); };
+  child.stdout?.on('data', (chunk) => { stdout += String(chunk); touch(); });
+  child.stderr?.on('data', (chunk) => { stderr += String(chunk); touch(); });
+  child.on('error', (error) => { stderr += String(error?.message || error); failureMode ||= 'crash'; });
+
+  const stopFor = async (mode) => {
+    if (failureMode) return;
+    failureMode = mode;
+    await terminateChild(child.pid);
+  };
+
+  const timeoutTimer = setTimeout(() => { void stopFor('timeout'); }, timeout);
+  const stallTimer = setInterval(() => {
+    const size = Buffer.byteLength(stdout) + Buffer.byteLength(stderr);
+    if (size !== lastBytes) {
+      lastBytes = size;
+      return;
+    }
+    if (Date.now() - lastChange >= stallThresholdMs) void stopFor(inferStallMode(stdout, stderr));
+  }, stallCheckIntervalMs);
+  timeoutTimer.unref?.();
+  stallTimer.unref?.();
+
+  await new Promise((resolve) => child.on('close', (code) => { exitCode = code; resolve(); }));
+  clearTimeout(timeoutTimer);
+  clearInterval(stallTimer);
+
+  const fileOutput = resultFile && existsSync(resultFile) ? readFileSync(resultFile, 'utf8') : '';
+  const output = fileOutput || stdout;
+  const ok = failureMode == null && exitCode === 0;
+  return createResult(ok, {
+    output,
+    stderr,
+    exitCode,
+    duration: Date.now() - startedAt,
+    failureMode: ok ? null : (failureMode || 'crash'),
+  });
+}

package/hub/codex-adapter.mjs

@@ -0,0 +1,190 @@
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { runPreflight } from './codex-preflight.mjs';
+import { withRetry } from './workers/worker-utils.mjs';
+import { buildExecCommand } from './codex-compat.mjs';
+import {
+  createCircuitBreaker,
+  createResult,
+  appendWarnings,
+  normalizePathForShell,
+  shellQuote,
+  runProcess,
+} from './cli-adapter-base.mjs';
+
+const breaker = createCircuitBreaker();
+
+// ── Codex-specific stall inference ──────────────────────────────
+
+function inferStallMode(stdout, stderr) {
+  const text = `${stdout}\n${stderr}`.toLowerCase();
+  if (/(approval|approve|permission|sandbox|bypass)/u.test(text)) return 'approval_stall';
+  if (/\bmcp\b|context7|playwright|tavily|exa|brave|sequential|server/u.test(text)) return 'mcp_stall';
+  return 'timeout';
+}
+
+// ── Codex command building ──────────────────────────────────────
+
+function commandWithOverrides(command, prompt, codexPath, overrides = []) {
+  let next = codexPath ? command.replace(/^codex\b/u, shellQuote(codexPath)) : command;
+  if (!overrides.length) return next;
+  const promptArg = JSON.stringify(prompt);
+  const flags = overrides.flatMap((value) => ['-c', shellQuote(value)]).join(' ');
+  return next.endsWith(promptArg)
+    ? `${next.slice(0, -promptArg.length)}${flags} ${promptArg}`
+    : `${next} ${flags}`;
+}
+
+function buildOverrides(requested, excluded) {
+  return [...new Set((requested || []).filter((name) => (excluded || []).includes(name)))]
+    .map((name) => `mcp_servers.${name}.enabled=false`);
+}
+
+function buildAttempts(opts, preflight) {
+  const timeout = Number.isFinite(opts.timeout) ? opts.timeout : 300_000;
+  const requested = Array.isArray(opts.mcpServers) ? [...opts.mcpServers] : [];
+  const base = {
+    timeout,
+    profile: opts.profile,
+    requested,
+    excluded: [...(preflight.excludeMcpServers || [])],
+    forceBypass: preflight.needsBypass,
+  };
+  if (opts.retryOnFail === false) return [base];
+  return [
+    base,
+    { ...base, timeout: timeout * 2, excluded: requested, forceBypass: true },
+  ];
+}
+
+// ── Launch script ───────────────────────────────────────────────
+
+function createLaunchScriptText(opts) {
+  const parts = ['codex'];
+  if (opts.profile) parts.push('--profile', shellQuote(opts.profile));
+  parts.push(
+    'exec',
+    '--dangerously-bypass-approvals-and-sandbox',
+    '--skip-git-repo-check',
+    '$(cat "$PROMPT_FILE")',
+  );
+  return [
+    '#!/usr/bin/env bash',
+    'set -euo pipefail',
+    `cd ${shellQuote(normalizePathForShell(opts.workdir))}`,
+    `PROMPT_FILE=${shellQuote(normalizePathForShell(opts.promptFile))}`,
+    `TFX_CODEX_TIMEOUT_MS=${shellQuote(String(opts.timeout ?? ''))}`,
+    parts.join(' '),
+    '',
+  ].join('\n');
+}
+
+export function buildLaunchScript(opts = {}) {
+  const dir = join(tmpdir(), 'triflux-codex-launch');
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, `${String(opts.id || 'launch')}.sh`);
+  writeFileSync(path, createLaunchScriptText(opts), 'utf8');
+  return path;
+}
+
+// ── Exec args builder ───────────────────────────────────────────
+
+export function buildExecArgs(opts = {}) {
+  const prompt = typeof opts.prompt === 'string' ? opts.prompt : '';
+  const command = buildExecCommand(prompt, opts.resultFile || null, {
+    profile: opts.profile,
+    skipGitRepoCheck: true,
+    sandboxBypass: true,
+  });
+
+  if (!prompt) return command.replace(/\s+""$/u, '');
+
+  const quotedPrompt = JSON.stringify(prompt);
+  if (/^\(Get-Content\b[\s\S]*\)$/u.test(prompt) && command.endsWith(quotedPrompt)) {
+    return `${command.slice(0, -quotedPrompt.length)}${prompt}`;
+  }
+
+  return command;
+}
+
+// ── Codex execution ─────────────────────────────────────────────
+
+async function runCodex(prompt, workdir, preflight, attempt) {
+  const dir = join(tmpdir(), 'triflux-codex-exec');
+  mkdirSync(dir, { recursive: true });
+  const resultFile = join(dir, `codex-${Date.now()}-${Math.random().toString(36).slice(2)}.txt`);
+  const command = commandWithOverrides(
+    buildExecCommand(prompt, resultFile, {
+      profile: attempt.profile,
+      skipGitRepoCheck: true,
+      sandboxBypass: attempt.forceBypass,
+    }),
+    prompt,
+    preflight.codexPath,
+    buildOverrides(attempt.requested, attempt.excluded),
+  );
+  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, subcommand: 'exec' });
+  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 runCodex(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/codex-compat.mjs

@@ -0,0 +1,78 @@
+// hub/team/codex-compat.mjs — Codex CLI 버전 어댑터
+// Codex 0.117.0+ (Rust 리라이트): exec 서브커맨드 기반
+import { execSync } from "node:child_process";
+
+let _cachedVersion = null;
+
+/**
+ * `codex --version` 실행 결과를 파싱하여 마이너 버전 숫자 반환.
+ * 파싱 실패 시 0 반환 (구버전으로 간주).
+ * @returns {number} 마이너 버전 (예: 0.117.0 → 117)
+ */
+export function getCodexVersion() {
+  if (_cachedVersion !== null) return _cachedVersion;
+  try {
+    const out = execSync("codex --version", { encoding: "utf8", timeout: 5000 }).trim();
+    // "codex 0.117.0" 또는 "0.117.0" 형식 대응
+    const m = out.match(/(\d+)\.(\d+)\.(\d+)/);
+    _cachedVersion = m ? parseInt(m[2], 10) : 0;
+  } catch {
+    _cachedVersion = 0;
+  }
+  return _cachedVersion;
+}
+
+/**
+ * 최소 마이너 버전 이상인지 확인.
+ * @param {number} minMinor
+ * @returns {boolean}
+ */
+export function gte(minMinor) {
+  return getCodexVersion() >= minMinor;
+}
+
+/**
+ * Codex CLI 기능별 분기 객체.
+ * 117 = 0.117.0 (Rust 리라이트, exec 서브커맨드 도입)
+ */
+export const FEATURES = {
+  /** exec 서브커맨드 사용 가능 여부 */
+  get execSubcommand() { return gte(117); },
+  /** --output-last-message 플래그 지원 여부 */
+  get outputLastMessage() { return gte(117); },
+  /** --color never 플래그 지원 여부 */
+  get colorNever() { return gte(117); },
+  /** 플러그인 시스템 지원 여부 (향후 확장용) */
+  get pluginSystem() { return gte(120); },
+};
+
+/**
+ * long-form 플래그 기반 명령 빌더.
+ * @param {string} prompt
+ * @param {string|null} resultFile — null이면 --output-last-message 생략
+ * @param {{ profile?: string, skipGitRepoCheck?: boolean, sandboxBypass?: boolean }} [opts]
+ * @returns {string} 실행할 셸 커맨드
+ */
+export function buildExecCommand(prompt, resultFile = null, opts = {}) {
+  const { profile, skipGitRepoCheck = true, sandboxBypass = true } = opts;
+
+  const parts = ["codex"];
+  if (profile) parts.push("--profile", profile);
+
+  if (FEATURES.execSubcommand) {
+    parts.push("exec");
+    if (sandboxBypass) parts.push("--dangerously-bypass-approvals-and-sandbox");
+    if (skipGitRepoCheck) parts.push("--skip-git-repo-check");
+    if (resultFile && FEATURES.outputLastMessage) {
+      parts.push("--output-last-message", resultFile);
+    }
+    if (FEATURES.colorNever) parts.push("--color", "never");
+  } else {
+    // 구버전 fallback
+    parts.push("--dangerously-bypass-approvals-and-sandbox");
+    if (skipGitRepoCheck) parts.push("--skip-git-repo-check");
+  }
+
+  parts.push(JSON.stringify(prompt));
+  return parts.join(" ");
+}

package/hub/codex-preflight.mjs

@@ -0,0 +1,147 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+import { whichCommandAsync } from './platform.mjs';
+import { getCodexVersion } from './codex-compat.mjs';
+
+const MIN_RECOMMENDED_MINOR = 118;
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function readConfigText(configPath = join(homedir(), '.codex', 'config.toml')) {
+  if (!existsSync(configPath)) return '';
+  try {
+    return readFileSync(configPath, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function readTomlString(text, key) {
+  const match = String(text).match(new RegExp(`^\\s*${escapeRegExp(key)}\\s*=\\s*"([^"]*)"\\s*$`, 'mu'));
+  return match?.[1] ?? null;
+}
+
+function readSection(text, name) {
+  const lines = String(text).split(/\r?\n/u);
+  const header = `[${name}]`;
+  const start = lines.findIndex((line) => line.trim() === header);
+  if (start < 0) return '';
+  const body = [];
+  for (const line of lines.slice(start + 1)) {
+    if (/^\s*\[[^\]]+\]\s*$/u.test(line)) break;
+    body.push(line);
+  }
+  return body.join('\n');
+}
+
+async function checkCodexInstalled() {
+  const codexPath = await whichCommandAsync('codex');
+  if (codexPath) return { codexPath, ok: true, warnings: [] };
+  return {
+    codexPath: null,
+    ok: false,
+    warnings: ['Codex CLI not found. Install Codex and ensure `codex` is available on PATH.'],
+  };
+}
+
+function checkCodexVersion() {
+  const version = getCodexVersion();
+  const warnings = version >= MIN_RECOMMENDED_MINOR
+    ? []
+    : [`Codex CLI 0.${version}.x detected; 0.${MIN_RECOMMENDED_MINOR}.x or newer is recommended.`];
+  return { version, warnings };
+}
+
+function checkApprovalMode(configText, opts = {}) {
+  const approvalMode = readTomlString(configText, 'approval_mode');
+  const sandbox = readTomlString(configText, 'sandbox');
+  const subcommand = opts.subcommand || 'exec';
+  return {
+    needsBypass: subcommand === 'exec' || approvalMode !== 'full-auto',
+    approvalMode,
+    sandbox,
+  };
+}
+
+async function verifyServerHealth(name, configText) {
+  const section = readSection(configText, `mcp_servers.${name}`);
+  if (!section) return { ok: false, warning: `MCP server '${name}' is not configured.` };
+  if (/^\s*enabled\s*=\s*false\s*$/mu.test(section)) {
+    return { ok: false, warning: `MCP server '${name}' is disabled in config.toml.` };
+  }
+
+  const command = readTomlString(section, 'command');
+  if (command) {
+    const resolved = await whichCommandAsync(command);
+    return resolved
+      ? { ok: true, warning: '' }
+      : { ok: false, warning: `MCP server '${name}' command not found: ${command}` };
+  }
+
+  const url = readTomlString(section, 'url');
+  if (!url || !/^https?:\/\//u.test(url)) return { ok: true, warning: '' };
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(2000) });
+    return response.status < 500
+      ? { ok: true, warning: '' }
+      : { ok: false, warning: `MCP server '${name}' returned HTTP ${response.status}.` };
+  } catch {
+    return { ok: false, warning: `MCP server '${name}' is unreachable at ${url}.` };
+  }
+}
+
+async function checkMcpHealth(mcpServers, configText) {
+  const excludeMcpServers = [];
+  const warnings = [];
+
+  for (const name of Array.isArray(mcpServers) ? mcpServers : []) {
+    const server = String(name ?? '').trim();
+    if (!server) continue;
+    const result = await verifyServerHealth(server, configText);
+    if (!result.ok) excludeMcpServers.push(server);
+    if (result.warning) warnings.push(result.warning);
+  }
+
+  return { excludeMcpServers, warnings };
+}
+
+export async function runPreflight(opts = {}) {
+  const install = await checkCodexInstalled();
+  if (!install.ok) {
+    return {
+      codexPath: null,
+      version: 0,
+      needsBypass: true,
+      excludeMcpServers: [],
+      warnings: install.warnings,
+      ok: false,
+    };
+  }
+
+  const warnings = [...install.warnings];
+  const { version, warnings: versionWarnings } = checkCodexVersion();
+  warnings.push(...versionWarnings);
+
+  const configText = readConfigText(opts.configPath);
+  const approval = checkApprovalMode(configText, opts);
+  if (approval.approvalMode !== 'full-auto') {
+    warnings.push(`approval_mode is '${approval.approvalMode || 'unset'}'; bypass flag will be used.`);
+  }
+  if (approval.sandbox) warnings.push(`sandbox mode from config.toml: ${approval.sandbox}`);
+
+  const mcp = await checkMcpHealth(opts.mcpServers, configText);
+  warnings.push(...mcp.warnings);
+
+  return {
+    codexPath: install.codexPath,
+    version,
+    needsBypass: approval.needsBypass,
+    excludeMcpServers: mcp.excludeMcpServers,
+    warnings,
+    ok: true,
+  };
+}

package/hub/delegator/contracts.mjs

@@ -0,0 +1,37 @@
+export const DELEGATOR_MCP_SERVER_INFO = Object.freeze({
+  name: 'triflux-delegator',
+  version: '0.1.0',
+});
+
+export const DELEGATOR_TOOL_NAMES = Object.freeze({
+  delegate: 'delegate',
+  delegateReply: 'delegate-reply',
+  status: 'status',
+});
+
+export const DELEGATOR_PIPE_ACTIONS = Object.freeze({
+  delegate: 'delegator_delegate',
+  delegateReply: 'delegator_reply',
+  status: 'delegator_status',
+});
+
+export const DELEGATOR_JOB_STATUSES = Object.freeze([
+  'queued',
+  'running',
+  'waiting_reply',
+  'completed',
+  'failed',
+]);
+
+export const DELEGATOR_MODES = Object.freeze([
+  'sync',
+  'async',
+]);
+
+export const DELEGATOR_PROVIDERS = Object.freeze([
+  'auto',
+  'codex',
+  'gemini',
+]);
+
+export const DELEGATOR_SCHEMA_URL = new URL('./schema/delegator-tools.schema.json', import.meta.url);

package/hub/delegator/index.mjs

@@ -0,0 +1,14 @@
+export {
+  DELEGATOR_JOB_STATUSES,
+  DELEGATOR_MCP_SERVER_INFO,
+  DELEGATOR_MODES,
+  DELEGATOR_PIPE_ACTIONS,
+  DELEGATOR_PROVIDERS,
+  DELEGATOR_SCHEMA_URL,
+  DELEGATOR_TOOL_NAMES,
+} from './contracts.mjs';
+export { DelegatorService } from './service.mjs';
+export {
+  getDelegatorMcpToolDefinitions,
+  loadDelegatorSchemaBundle,
+} from './tool-definitions.mjs';