triflux 10.4.0 → 10.7.0

package/skills/tfx-swarm/SKILL.md.tmpl

@@ -0,0 +1,218 @@
+---
+name: tfx-swarm
+description: "tfx-swarm — 다중 기기 x 다중 모델 스웜 오케스트레이션"
+triggers:
+  - swarm
+  - 스웜
+  - 병렬 실행
+  - codex-swarm
+---
+
+# {{SKILL_NAME}} — 다중 기기 x 다중 모델 스웜 오케스트레이션
+
+{{> base}}
+
+> **Multi-Machine x Multi-Model Swarm.** PRD 하나로 로컬과 원격 머신에서
+> Claude + Codex + Gemini를 병렬 실행하고, file-lease로 충돌을 방지하며,
+> 결과를 자동 통합한다. triflux의 킬러 스킬.
+
+## 트리거
+
+- `swarm`, `스웜`, `병렬 실행`, `다중 워커`, `PRD 실행`, `swarm launch`
+- `codex-swarm` (backward compat -> 이 스킬로 라우팅)
+
+## 핵심 기능
+
+| 기능 | 설명 |
+|------|------|
+| **다중 모델** | shard별 `agent: codex\|gemini\|claude` 지정. 작업 특성에 맞는 모델 배치 |
+| **다중 기기** | shard별 `host: <ssh-host>` 지정. 로컬/원격 혼합 실행 |
+| **File Lease** | shard별 파일 소유권. 동일 파일 동시 수정 방지 |
+| **Redundant Execution** | critical shard는 다른 모델로 이중 실행 후 reconcile |
+| **자동 통합** | 의존 순서대로 merge. 원격 shard는 SSH 경유 fetch |
+| **장애 폴백** | rate limit -> 다른 모델로 자동 전환 (codex<->gemini<->claude) |
+
+## 전제조건
+
+- psmux >= 3.3.0
+- Hub 실행 중 (`curl -sf http://127.0.0.1:27888/status`)
+- Codex CLI 또는 Gemini CLI (사용할 agent에 따라)
+- 원격 shard 사용 시: SSH 키 인증 + 원격 머신에 Claude Code 설치
+- 프로젝트에 `docs/prd/` 디렉토리 존재
+
+## 실행 흐름
+
+### Step 1: PRD 탐색
+
+```bash
+find docs/prd -name '*.md' -not -name '_template.md' -not -path '*/archived/*' | sort
+```
+
+AskUserQuestion으로 실행할 PRD 선택. 복수 선택 시 각각 독립 shard.
+
+### Step 2: 원격/모델 구성 확인
+
+PRD 파싱 후, shard에 `host:` 필드가 있으면 AskUserQuestion으로 원격 실행 여부를 확인한다.
+
+AskUserQuestion:
+
+> PRD에 원격 호스트가 지정된 shard가 있습니다:
+> - `{shard_name}` -> `{host}` ({agent})
+>
+> 원격 실행을 어떻게 할까요?
+
+Options:
+- A) 원격 포함 실행 (PRD 그대로) — 로컬+원격 혼합
+- B) 전부 로컬에서 실행 — host 필드 무시
+- C) 원격만 실행 — 로컬 shard 건너뛰기
+
+PRD에 다중 agent가 지정된 경우에도 AskUserQuestion:
+
+> PRD에 여러 모델이 지정되어 있습니다:
+> - codex: {N}개 shard
+> - gemini: {N}개 shard
+> - claude: {N}개 shard
+>
+> 모델 배치를 어떻게 할까요?
+
+Options:
+- A) PRD 그대로 — shard별 지정 모델 사용 (권장)
+- B) 전부 Codex로 — 단일 모델
+- C) 전부 Gemini로 — 단일 모델
+
+### Step 3: 계획 생성
+
+```javascript
+import { planSwarm } from '../../hub/team/swarm-planner.mjs';
+
+const swarmPlan = planSwarm(selectedPrdPath);
+```
+
+계획을 사용자에게 보여주고 승인 요청:
+- shard 수, 파일 배분, lease 맵, merge 순서
+- 원격 shard 표시 (host 정보)
+- 모델 배분 표시 (agent 정보)
+- critical shard 표시 (redundant execution 대상)
+
+### Step 4: Hypervisor 실행
+
+```javascript
+import { createSwarmHypervisor } from '../../hub/team/swarm-hypervisor.mjs';
+
+const hyper = createSwarmHypervisor({
+  workdir: process.cwd(),
+  logsDir: join(process.cwd(), '.triflux', 'swarm-logs'),
+  maxRestarts: 2,
+});
+
+const run = hyper.launch(swarmPlan);
+```
+
+실행 중 상태 모니터링:
+- `hyper.on('shardLaunched', ...)` -> 진행 표시
+- `hyper.on('shardCompleted', ...)` -> 완료/실패 표시
+- `hyper.on('warning', ...)` -> 경고 (파일 충돌 등)
+
+원격 shard 실행 시:
+1. `probeRemoteEnv(host)` -> 원격 환경 감지 (OS, shell, Claude 경로)
+2. conductor가 `remote: true` 설정으로 SSH 경유 세션 실행
+3. 완료 후 `fetchRemoteShard()`로 원격 브랜치를 로컬로 fetch
+
+### Step 5: 결과 검증 + 통합
+
+```javascript
+const status = hyper.getStatus();
+// status.completedShards, status.failedShards, status.workers
+```
+
+통합 결과를 사용자에게 보고:
+- 성공: merged shard 목록 (로컬/원격 구분 표시)
+- 실패: 충돌/실패 shard 목록 + 수동 해결 안내
+
+### Step 6: 정리
+
+```javascript
+await hyper.shutdown('completed');
+```
+
+## PRD 예제: 다중 기기 x 다중 모델
+
+```markdown
+## Shard: auth-refactor
+- agent: codex
+- files: src/auth.mjs, src/middleware/jwt.mjs
+- prompt: JWT 인증 미들웨어 리팩터링
+
+## Shard: ui-dashboard
+- agent: gemini
+- files: src/ui/dashboard.mjs, src/ui/charts.mjs
+- prompt: 대시보드 UI 개선
+
+## Shard: security-audit
+- agent: claude
+- host: ryzen5-7600
+- files: src/security.mjs
+- critical: true
+- prompt: 보안 취약점 감사
+
+## Shard: perf-optimization
+- agent: codex
+- host: m2
+- files: src/engine/optimizer.mjs
+- depends: auth-refactor
+- prompt: 성능 최적화 (auth 리팩터 완료 후)
+```
+
+위 PRD 하나로: Codex(로컬) + Gemini(로컬) + Claude(ryzen5-7600) + Codex(m2) 4개 워커가 병렬 실행된다.
+security-audit는 `critical: true`이므로 다른 모델로 이중 실행 후 reconcile.
+
+## PRD Shard 필드 레퍼런스
+
+| 필드 | 필수 | 기본값 | 설명 |
+|------|------|--------|------|
+| `agent` | - | `codex` | 실행 모델: `codex`, `gemini`, `claude` |
+| `host` | - | (로컬) | SSH 호스트. 미지정 시 로컬 실행 |
+| `files` | O | - | shard가 수정할 파일 목록 (file-lease 대상) |
+| `depends` | - | - | 의존하는 shard 이름. 해당 shard 완료 후 실행 |
+| `critical` | - | `false` | `true`면 다른 모델로 이중 실행 + reconcile |
+| `mcp` | - | - | 필요한 MCP 서버 목록 |
+| `prompt` | O | - | shard 실행 프롬프트. `\|`로 멀티라인 |
+
+## 제약
+
+- `codex exec` / `gemini -p` 직접 호출 금지 (headless-guard)
+- MAX_CONCURRENCY 기본 4 (WT 프리징 방지)
+- WT 조작 간 sleep 2s (race-guard)
+- config.toml과 CLI 플래그 중복 지정 금지
+
+## Redundant Execution
+
+critical shard (hard lease 또는 고위험 파일)에 대해:
+
+```javascript
+import { shouldRunRedundant, reconcile } from '../../hub/team/swarm-reconciler.mjs';
+
+if (shouldRunRedundant(shard)) {
+  // primary + verifier 이중 실행
+  const decision = await reconcile(primaryResult, verifierResult);
+  // decision.selected: 'primary' | 'verifier' | 'hitl'
+}
+```
+
+HITL fallback 시 AskUserQuestion으로 사용자에게 선택 요청.
+
+## 장애 처리
+
+| 장애 | 분류 | 대응 |
+|------|------|------|
+| 워커 크래시 | F1 | conductor auto-restart (최대 2회) |
+| Rate limit | F2 | 다른 모델로 자동 전환 (codex->gemini->claude) |
+| Stall | F3 | health probe 감지 -> kill -> restart |
+| File lease 위반 | F4 | 워커 변경 revert, shard 실패 처리 |
+| Merge 충돌 | F5 | 충돌 해결 재시도 |
+
+## 기존 스킬과의 관계
+
+- **tfx-codex-swarm**: deprecated. 이 스킬로 통합됨 (backward compat alias)
+- **tfx-remote-spawn**: 단독 원격 세션 관리(list, attach, send)용으로 유지. swarm은 다중 shard 병렬 관리
+- **tfx-multi**: Claude Native Teams 기반 로컬 오케스트레이션. swarm은 PRD 기반 worktree 분할

package/tui/codex-profile.mjs

@@ -0,0 +1,457 @@
+#!/usr/bin/env node
+// tui/codex-profile.mjs — Interactive Codex Profile Manager
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  BOLD,
+  box,
+  CYAN,
+  clear,
+  confirm,
+  DIM,
+  divider,
+  fail,
+  GREEN,
+  info,
+  input,
+  label,
+  ok,
+  onExit,
+  RED,
+  RESET,
+  select,
+  showCursor,
+  table,
+  WHITE,
+  warn,
+  YELLOW,
+} from "./core.mjs";
+
+const CODEX_DIR = join(homedir(), ".codex");
+const CONFIG_PATH = join(CODEX_DIR, "config.toml");
+
+const KNOWN_MODELS = [
+  { label: "gpt-5.4", hint: "최신 플래그십" },
+  { label: "gpt-5.3-codex", hint: "코딩 특화" },
+  { label: "gpt-5.1-codex-mini", hint: "경량 Spark" },
+  { label: "o3", hint: "추론 특화" },
+  { label: "o4-mini", hint: "추론 경량" },
+  { label: "직접 입력", hint: "" },
+];
+
+const EFFORT_LEVELS = [
+  { label: "low", hint: "빠른 응답, 최소 추론" },
+  { label: "medium", hint: "균형 잡힌 추론" },
+  { label: "high", hint: "깊은 추론" },
+  { label: "xhigh", hint: "최대 추론 (느림)" },
+];
+
+// ── TOML Parsing ──
+
+function readConfig() {
+  if (!existsSync(CONFIG_PATH)) return { raw: "", defaults: {}, profiles: [] };
+  const raw = readFileSync(CONFIG_PATH, "utf8");
+  return { raw, ...parseConfig(raw) };
+}
+
+function parseConfig(raw) {
+  const lines = raw.split("\n");
+  const defaults = {};
+  const profiles = [];
+  let currentSection = null;
+  let currentProfile = null;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    const sectionMatch = trimmed.match(/^\[(.+)\]$/);
+    if (sectionMatch) {
+      const name = sectionMatch[1];
+      const profileMatch = name.match(/^profiles\.(\w+)$/);
+      if (profileMatch) {
+        currentSection = "profile";
+        currentProfile = { name: profileMatch[1] };
+        profiles.push(currentProfile);
+      } else {
+        currentSection = name;
+        currentProfile = null;
+      }
+      continue;
+    }
+
+    const kvMatch = trimmed.match(/^(\w+)\s*=\s*(.+)$/);
+    if (kvMatch) {
+      const [, key, rawVal] = kvMatch;
+      const value = rawVal.replace(/^["']|["']$/g, "").trim();
+      if (currentSection === "profile" && currentProfile) {
+        currentProfile[key] = value;
+      } else if (!currentSection) {
+        defaults[key] = value;
+      }
+    }
+  }
+
+  return { defaults, profiles };
+}
+
+function writeProfile(raw, profileName, props) {
+  const lines = raw.split("\n");
+  const sectionRe = new RegExp(`^\\[profiles\\.${escRe(profileName)}\\]\\s*$`);
+  let inSection = false;
+  let sectionStart = -1;
+  let sectionEnd = lines.length;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (sectionRe.test(lines[i].trim())) {
+      inSection = true;
+      sectionStart = i;
+      continue;
+    }
+    if (inSection && lines[i].trim().startsWith("[")) {
+      sectionEnd = i;
+      break;
+    }
+  }
+
+  if (sectionStart === -1) {
+    // Append new profile section
+    const newLines = [`[profiles.${profileName}]`];
+    for (const [k, v] of Object.entries(props)) {
+      newLines.push(`${k} = "${v}"`);
+    }
+    return raw.trimEnd() + "\n" + newLines.join("\n") + "\n";
+  }
+
+  // Replace existing section body
+  const newBody = [];
+  for (const [k, v] of Object.entries(props)) {
+    newBody.push(`${k} = "${v}"`);
+  }
+  lines.splice(sectionStart + 1, sectionEnd - sectionStart - 1, ...newBody);
+  return lines.join("\n");
+}
+
+function deleteProfile(raw, profileName) {
+  const lines = raw.split("\n");
+  const sectionRe = new RegExp(`^\\[profiles\\.${escRe(profileName)}\\]\\s*$`);
+  let inSection = false;
+  let start = -1;
+  let end = lines.length;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (sectionRe.test(lines[i].trim())) {
+      inSection = true;
+      start = i;
+      continue;
+    }
+    if (inSection && lines[i].trim().startsWith("[")) {
+      end = i;
+      break;
+    }
+  }
+
+  if (start === -1) return raw;
+  // Remove trailing blank lines too
+  while (end < lines.length && lines[end].trim() === "") end++;
+  lines.splice(start, end - start);
+  return lines.join("\n");
+}
+
+function setDefault(raw, key, value) {
+  const lines = raw.split("\n");
+  const keyRe = new RegExp(`^${escRe(key)}\\s*=`);
+
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim().startsWith("[")) break; // hit first section
+    if (keyRe.test(lines[i].trim())) {
+      lines[i] = `${key} = "${value}"`;
+      return lines.join("\n");
+    }
+  }
+
+  // Key not found — insert before first section
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim().startsWith("[")) {
+      lines.splice(i, 0, `${key} = "${value}"`);
+      return lines.join("\n");
+    }
+  }
+
+  return raw + `\n${key} = "${value}"\n`;
+}
+
+function escRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// ── UI Flows ──
+
+function showStatus(config) {
+  const { defaults, profiles } = config;
+
+  console.log();
+  label("기본 모델", `${WHITE}${defaults.model || "미설정"}${RESET}`);
+  label(
+    "기본 Effort",
+    `${WHITE}${defaults.model_reasoning_effort || "미설정"}${RESET}`,
+  );
+  console.log();
+
+  if (profiles.length === 0) {
+    warn("등록된 프로파일이 없습니다.");
+    return;
+  }
+
+  const headers = ["프로파일", "모델", "Effort", "기타"];
+  const rows = profiles.map((p) => {
+    const extras = Object.entries(p)
+      .filter(([k]) => !["name", "model", "model_reasoning_effort"].includes(k))
+      .map(([k, v]) => `${k}=${v}`)
+      .join(", ");
+    return [
+      `${CYAN}${p.name}${RESET}`,
+      p.model || DIM + "inherit" + RESET,
+      effortColor(p.model_reasoning_effort),
+      extras ? `${DIM}${extras}${RESET}` : "",
+    ];
+  });
+
+  table(headers, rows);
+}
+
+function effortColor(effort) {
+  if (!effort) return `${DIM}inherit${RESET}`;
+  const colors = { low: GREEN, medium: CYAN, high: YELLOW, xhigh: RED };
+  return `${colors[effort] || ""}${effort}${RESET}`;
+}
+
+async function pickModel(current) {
+  const idx = KNOWN_MODELS.findIndex((m) => m.label === current);
+  const choice = await select("모델 선택", KNOWN_MODELS, {
+    initial: Math.max(0, idx),
+  });
+  if (!choice) return null;
+  if (choice.value.label === "직접 입력") {
+    return await input("모델 ID", current || "");
+  }
+  return choice.value.label;
+}
+
+async function pickEffort(current) {
+  const idx = EFFORT_LEVELS.findIndex((e) => e.label === current);
+  const choice = await select("Reasoning Effort 선택", EFFORT_LEVELS, {
+    initial: Math.max(0, idx),
+  });
+  if (!choice) return null;
+  return choice.value.label;
+}
+
+async function editProfile(config) {
+  const { profiles } = config;
+  if (profiles.length === 0) {
+    warn("편집할 프로파일이 없습니다.");
+    return config;
+  }
+
+  const options = profiles.map((p) => ({
+    label: p.name,
+    hint: `${DIM}${p.model || "inherit"} / ${p.model_reasoning_effort || "inherit"}${RESET}`,
+  }));
+
+  const picked = await select("편집할 프로파일", options);
+  if (!picked) return config;
+
+  const profile = profiles[picked.index];
+  console.log();
+  info(
+    `현재: ${BOLD}${profile.name}${RESET} → ${profile.model} / ${profile.model_reasoning_effort}`,
+  );
+
+  const newModel = await pickModel(profile.model);
+  if (newModel === null) return config;
+
+  const newEffort = await pickEffort(profile.model_reasoning_effort);
+  if (newEffort === null) return config;
+
+  console.log();
+  info(
+    `변경: ${profile.model} → ${BOLD}${newModel}${RESET}, ${profile.model_reasoning_effort} → ${BOLD}${newEffort}${RESET}`,
+  );
+
+  if (!(await confirm("저장하시겠습니까?"))) return config;
+
+  const props = { model: newModel, model_reasoning_effort: newEffort };
+  // Preserve extra props (like model_temperature)
+  for (const [k, v] of Object.entries(profile)) {
+    if (!["name", "model", "model_reasoning_effort"].includes(k)) props[k] = v;
+  }
+
+  const raw = writeProfile(config.raw, profile.name, props);
+  save(raw);
+  ok(`${profile.name} 프로파일 저장 완료`);
+  return readConfig();
+}
+
+async function editDefault(config) {
+  const { defaults } = config;
+  info(`현재 기본 모델: ${BOLD}${defaults.model || "미설정"}${RESET}`);
+  info(
+    `현재 기본 Effort: ${BOLD}${defaults.model_reasoning_effort || "미설정"}${RESET}`,
+  );
+
+  const newModel = await pickModel(defaults.model);
+  if (newModel === null) return config;
+
+  const newEffort = await pickEffort(defaults.model_reasoning_effort);
+  if (newEffort === null) return config;
+
+  console.log();
+  info(
+    `변경: ${defaults.model} → ${BOLD}${newModel}${RESET}, ${defaults.model_reasoning_effort} → ${BOLD}${newEffort}${RESET}`,
+  );
+
+  if (!(await confirm("저장하시겠습니까?"))) return config;
+
+  let raw = setDefault(config.raw, "model", newModel);
+  raw = setDefault(raw, "model_reasoning_effort", newEffort);
+  save(raw);
+  ok("기본 설정 저장 완료");
+  return readConfig();
+}
+
+async function addProfile(config) {
+  const name = await input("새 프로파일 이름");
+  if (!name) return config;
+
+  if (config.profiles.some((p) => p.name === name)) {
+    fail(`'${name}' 프로파일이 이미 존재합니다.`);
+    return config;
+  }
+
+  const model = await pickModel("");
+  if (!model) return config;
+
+  const effort = await pickEffort("");
+  if (!effort) return config;
+
+  console.log();
+  info(`추가: ${BOLD}${name}${RESET} → ${model} / ${effort}`);
+  if (!(await confirm("저장하시겠습니까?"))) return config;
+
+  const raw = writeProfile(config.raw, name, {
+    model,
+    model_reasoning_effort: effort,
+  });
+  save(raw);
+  ok(`${name} 프로파일 추가 완료`);
+  return readConfig();
+}
+
+async function removeProfile(config) {
+  const { profiles } = config;
+  if (profiles.length === 0) {
+    warn("삭제할 프로파일이 없습니다.");
+    return config;
+  }
+
+  const options = profiles.map((p) => ({ label: p.name, hint: `${p.model}` }));
+  const picked = await select("삭제할 프로파일", options);
+  if (!picked) return config;
+
+  const name = profiles[picked.index].name;
+  if (
+    !(await confirm(
+      `${RED}${name}${RESET} 프로파일을 삭제하시겠습니까?`,
+      false,
+    ))
+  ) {
+    return config;
+  }
+
+  const raw = deleteProfile(config.raw, name);
+  save(raw);
+  ok(`${name} 프로파일 삭제 완료`);
+  return readConfig();
+}
+
+function save(content) {
+  if (!existsSync(CODEX_DIR)) mkdirSync(CODEX_DIR, { recursive: true });
+
+  // Backup before write
+  if (existsSync(CONFIG_PATH)) {
+    const backupPath = CONFIG_PATH + ".bak";
+    copyFileSync(CONFIG_PATH, backupPath);
+  }
+
+  writeFileSync(CONFIG_PATH, content, "utf8");
+}
+
+// ── Main Loop ──
+
+const MENU = [
+  { label: "프로파일 모델 변경", hint: "모델/effort 수정" },
+  { label: "기본 모델 변경", hint: "top-level default" },
+  { label: "프로파일 추가", hint: "새 프로파일 생성" },
+  { label: "프로파일 삭제", hint: "기존 프로파일 제거" },
+  { label: "종료", hint: "Ctrl+C" },
+];
+
+async function main() {
+  onExit(() => {});
+  clear();
+
+  let config = readConfig();
+
+  if (!existsSync(CONFIG_PATH)) {
+    fail(`config.toml 미존재: ${CONFIG_PATH}`);
+    info("codex를 먼저 설치하거나 /tfx-setup을 실행하세요.");
+    process.exit(1);
+  }
+
+  while (true) {
+    box("Codex Profile Manager", 46);
+    showStatus(config);
+    console.log();
+
+    const choice = await select("작업 선택", MENU);
+    if (!choice || choice.index === 4) {
+      console.log();
+      info("종료합니다.");
+      showCursor();
+      break;
+    }
+
+    console.log();
+    switch (choice.index) {
+      case 0:
+        config = await editProfile(config);
+        break;
+      case 1:
+        config = await editDefault(config);
+        break;
+      case 2:
+        config = await addProfile(config);
+        break;
+      case 3:
+        config = await removeProfile(config);
+        break;
+    }
+
+    console.log();
+    divider(46);
+  }
+}
+
+main().catch((e) => {
+  showCursor();
+  console.error(e);
+  process.exit(1);
+});