@triflux/remote 10.0.0-alpha.1

package/hub/team/dashboard.mjs

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+// hub/team/dashboard.mjs — 실시간 팀 상태 표시 (v2.2)
+// tmux 의존 제거 — Hub task-list + native-supervisor 기반
+//
+// 실행:
+//   node hub/team/dashboard.mjs --session <세션이름> [--interval 2]
+//   node hub/team/dashboard.mjs --team <팀이름> [--interval 2]
+import { get } from "node:http";
+import { AMBER, GREEN, RED, GRAY, DIM, BOLD, RESET } from "./shared.mjs";
+
+/**
+ * HTTP GET JSON
+ * @param {string} url
+ * @returns {Promise<object|null>}
+ */
+function fetchJson(url) {
+  return new Promise((resolve) => {
+    const req = get(url, { timeout: 2000 }, (res) => {
+      let data = "";
+      res.on("data", (chunk) => (data += chunk));
+      res.on("end", () => {
+        try { resolve(JSON.parse(data)); } catch { resolve(null); }
+      });
+    });
+    req.on("error", () => resolve(null));
+    req.on("timeout", () => { req.destroy(); resolve(null); });
+  });
+}
+
+/**
+ * HTTP POST JSON (Hub bridge 용)
+ * @param {string} url
+ * @param {object} body
+ * @returns {Promise<object|null>}
+ */
+async function fetchPost(url, body = {}) {
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(2000),
+    });
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 진행률 바 생성
+ * @param {number} pct — 0~100
+ * @param {number} width — 바 너비 (기본 8)
+ * @returns {string}
+ */
+function progressBar(pct, width = 8) {
+  const filled = Math.round((pct / 100) * width);
+  const empty = width - filled;
+  return `${GREEN}${"█".repeat(filled)}${GRAY}${"░".repeat(empty)}${RESET}`;
+}
+
+/**
+ * 업타임 포맷
+ * @param {number} ms
+ * @returns {string}
+ */
+function formatUptime(ms) {
+  if (ms < 60000) return `${Math.round(ms / 1000)}초`;
+  if (ms < 3600000) return `${Math.round(ms / 60000)}분`;
+  return `${Math.round(ms / 3600000)}시간`;
+}
+
+/**
+ * task 상태 아이콘
+ * @param {string} status
+ * @returns {string}
+ */
+function statusIcon(status) {
+  switch (status) {
+    case "completed": return `${GREEN}✓${RESET}`;
+    case "in_progress": return `${AMBER}●${RESET}`;
+    case "failed": return `${RED}✗${RESET}`;
+    default: return `${GRAY}○${RESET}`;
+  }
+}
+
+/**
+ * 멤버 목록 구성: Hub tasks + supervisor + teamState 통합
+ * @param {Array} hubTasks — Hub bridge task-list 결과
+ * @param {Array} supervisorMembers — native-supervisor 멤버 상태
+ * @param {object} teamState — team-state.json 내용
+ * @returns {Array<{name: string, cli: string, status: string, subject: string, preview: string}>}
+ */
+function buildMemberList(hubTasks, supervisorMembers, teamState) {
+  const members = [];
+  const supervisorByName = new Map(supervisorMembers.map((m) => [m.name, m]));
+
+  // Hub tasks가 있으면 주 데이터 소스
+  if (hubTasks.length > 0) {
+    for (const task of hubTasks) {
+      const owner = task.owner || task.subject || "";
+      const sup = supervisorByName.get(owner);
+      members.push({
+        name: owner,
+        cli: task.metadata?.cli || sup?.cli || "",
+        status: task.status || "pending",
+        subject: task.subject || "",
+        preview: sup?.lastPreview || task.description?.slice(0, 80) || "",
+      });
+    }
+    return members;
+  }
+
+  // Supervisor 데이터 폴백
+  if (supervisorMembers.length > 0) {
+    for (const m of supervisorMembers) {
+      if (m.role === "lead") continue;
+      members.push({
+        name: m.name,
+        cli: m.cli || "",
+        status: m.status === "running" ? "in_progress" : m.status === "exited" ? "completed" : m.status,
+        subject: "",
+        preview: m.lastPreview || "",
+      });
+    }
+    return members;
+  }
+
+  // teamState 폴백 (하위 호환)
+  const panes = teamState?.panes || {};
+  for (const [, paneInfo] of Object.entries(panes).filter(([, v]) => v.role !== "dashboard" && v.role !== "lead")) {
+    members.push({
+      name: paneInfo.agentId || paneInfo.name || "?",
+      cli: paneInfo.cli || "",
+      status: "unknown",
+      subject: paneInfo.subtask || "",
+      preview: "",
+    });
+  }
+  return members;
+}
+
+/**
+ * 대시보드 렌더링 (v2.2: Hub/supervisor 기반)
+ * @param {string} sessionName — 세션 또는 팀 이름
+ * @param {object} opts
+ * @param {string} opts.hubUrl — Hub URL (기본 http://127.0.0.1:27888)
+ * @param {string} [opts.teamName] — Hub task-list 조회용 팀 이름
+ * @param {string} [opts.supervisorUrl] — native-supervisor 제어 URL
+ * @param {object} [opts.teamState] — team-state.json 내용 (하위 호환)
+ */
+export async function renderDashboard(sessionName, opts = {}) {
+  const {
+    hubUrl = "http://127.0.0.1:27888",
+    teamName,
+    supervisorUrl,
+    teamState = {},
+  } = opts;
+  const W = 50;
+  const border = "─".repeat(W);
+
+  // 데이터 수집 (병렬)
+  const [hubStatus, taskListRes, supervisorRes] = await Promise.all([
+    fetchJson(`${hubUrl}/status`),
+    teamName ? fetchPost(`${hubUrl}/bridge/team/task-list`, { team_name: teamName }) : null,
+    supervisorUrl ? fetchJson(`${supervisorUrl}/status`) : null,
+  ]);
+
+  const hubOnline = !!hubStatus;
+  const hubState = hubOnline ? `${GREEN}● online${RESET}` : `${RED}● offline${RESET}`;
+  const uptime = hubStatus?.hub?.uptime ? formatUptime(hubStatus.hub.uptime) : "-";
+  const queueSize = hubStatus?.hub?.queue_depth ?? 0;
+
+  // Hub task 데이터
+  const hubTasks = taskListRes?.ok ? (taskListRes.data?.tasks || []) : [];
+  const completedCount = hubTasks.filter((t) => t.status === "completed").length;
+  const totalCount = hubTasks.length;
+
+  // Supervisor 멤버 데이터
+  const supervisorMembers = supervisorRes?.ok ? (supervisorRes.data?.members || []) : [];
+
+  // 헤더
+  const progress = totalCount > 0 ? ` ${completedCount}/${totalCount}` : "";
+  console.log(`${AMBER}┌─ ${sessionName}${progress} ${GRAY}${"─".repeat(Math.max(0, W - sessionName.length - progress.length - 3))}${AMBER}┐${RESET}`);
+  console.log(`${AMBER}│${RESET} Hub: ${hubState}  Uptime: ${DIM}${uptime}${RESET}  Queue: ${DIM}${queueSize}${RESET}`);
+  console.log(`${AMBER}│${RESET}`);
+
+  // 멤버/워커 렌더링
+  const members = buildMemberList(hubTasks, supervisorMembers, teamState);
+
+  if (members.length === 0) {
+    console.log(`${AMBER}│${RESET}  ${DIM}에이전트 정보 없음${RESET}`);
+  } else {
+    for (const m of members) {
+      const icon = statusIcon(m.status);
+      const label = `[${m.name}]`;
+      const cliTag = m.cli ? m.cli.charAt(0).toUpperCase() + m.cli.slice(1) : "";
+
+      // 진행률 추정
+      const pct = m.status === "completed" ? 100
+        : m.status === "in_progress" ? 50
+        : m.status === "failed" ? 100
+        : 0;
+
+      console.log(`${AMBER}│${RESET}  ${BOLD}${label}${RESET} ${cliTag}  ${icon} ${m.status || "pending"}  ${progressBar(pct)}`);
+
+      // 미리보기: supervisor lastPreview > task subject
+      const preview = m.preview || m.subject || "";
+      if (preview) {
+        const truncated = preview.length > W - 8 ? preview.slice(0, W - 11) + "..." : preview;
+        console.log(`${AMBER}│${RESET}    ${DIM}> ${truncated}${RESET}`);
+      }
+      console.log(`${AMBER}│${RESET}`);
+    }
+  }
+
+  // 푸터
+  console.log(`${AMBER}└${GRAY}${border}${AMBER}┘${RESET}`);
+}
+
+/** team-state.json 로드 (세션별 파일 우선, fallback: team-state.json) */
+async function loadTeamState() {
+  try {
+    const { existsSync, readFileSync } = await import("node:fs");
+    const { join } = await import("node:path");
+    const { homedir } = await import("node:os");
+    const hubDir = join(homedir(), ".claude", "cache", "tfx-hub");
+    const sessionId = process.env.CLAUDE_SESSION_ID;
+    if (sessionId) {
+      const sessionPath = join(hubDir, `team-state-${sessionId}.json`);
+      if (existsSync(sessionPath)) return JSON.parse(readFileSync(sessionPath, "utf8"));
+    }
+    const legacyPath = join(hubDir, "team-state.json");
+    if (existsSync(legacyPath)) return JSON.parse(readFileSync(legacyPath, "utf8"));
+    return {};
+  } catch {
+    return {};
+  }
+}
+
+// ── CLI 실행 ──
+if (process.argv[1]?.includes("dashboard.mjs")) {
+  const sessionIdx = process.argv.indexOf("--session");
+  const teamIdx = process.argv.indexOf("--team");
+  const sessionName = sessionIdx !== -1 ? process.argv[sessionIdx + 1] : null;
+  const teamName = teamIdx !== -1 ? process.argv[teamIdx + 1] : null;
+  const intervalSec = parseInt(process.argv[process.argv.indexOf("--interval") + 1] || "2", 10);
+
+  const displayName = sessionName || teamName;
+  if (!displayName) {
+    console.error("사용법: node dashboard.mjs --session <세션이름> [--team <팀이름>] [--interval 2]");
+    process.exit(1);
+  }
+
+  // Ctrl+C로 종료
+  process.on("SIGINT", () => process.exit(0));
+
+  // 갱신 루프
+  while (true) {
+    const teamState = await loadTeamState();
+    const effectiveTeamName = teamName || null;
+    const supervisorUrl = teamState?.native?.controlUrl || null;
+
+    // 화면 클리어 (ANSI)
+    process.stdout.write("\x1b[2J\x1b[H");
+    await renderDashboard(displayName, {
+      teamName: effectiveTeamName,
+      supervisorUrl,
+      teamState,
+    });
+    console.log(`${DIM}  ${intervalSec}초 간격 갱신 | Ctrl+C로 종료${RESET}`);
+    await new Promise((r) => setTimeout(r, intervalSec * 1000));
+  }
+}

package/hub/team/handoff.mjs

@@ -0,0 +1,303 @@
+// hub/team/handoff.mjs — Worker → Lead handoff 프로토콜
+// HANDOFF 블록 파싱, 검증, fallback 생성, Lead 포맷팅
+// 설계: docs/design/handoff-schema-v7.md
+
+// ── enum 허용 값 ──
+const STATUS_VALUES = ["ok", "partial", "failed"];
+const LEAD_ACTION_VALUES = ["accept", "needs_read", "retry", "reassign"];
+const CONFIDENCE_VALUES = ["high", "medium", "low"];
+const RISK_VALUES = ["low", "med", "high"];
+const ERROR_STAGE_VALUES = ["dispatch", "execution", "timeout"];
+const YES_NO = ["yes", "no"];
+
+const TOKEN_HARD_CAP = 150;
+const HANDOFF_MARKER = "--- HANDOFF ---";
+
+/**
+ * 워커 프롬프트에 삽입할 HANDOFF 블록 생성 지시
+ */
+export const HANDOFF_INSTRUCTION = `
+After completing the task, you MUST output a HANDOFF block in exactly this format at the end of your response:
+
+--- HANDOFF ---
+status: ok | partial | failed
+lead_action: accept | needs_read | retry | reassign
+task: <1-3 word task type>
+files_changed: <comma-separated file paths, or "none">
+verdict: <one sentence conclusion>
+confidence: high | medium | low
+risk: low | med | high
+detail: <result file path if available, or "none">
+
+If the task failed, also include:
+error_stage: dispatch | execution | timeout
+retryable: yes | no
+partial_output: yes | no
+
+Rules:
+- The HANDOFF block must start with exactly "--- HANDOFF ---"
+- Each field must be on its own line as "key: value"
+- verdict must be a single concise sentence
+- Do not skip any required field
+`.trim();
+
+/**
+ * CLI 프롬프트 길이 제한을 고려한 축약 HANDOFF 지시
+ */
+export const HANDOFF_INSTRUCTION_SHORT =
+`After completing, output this block at the end:
+--- HANDOFF ---
+status: ok | partial | failed
+lead_action: accept | needs_read | retry | reassign
+verdict: <one sentence>
+files_changed: <comma-separated paths or "none">
+confidence: high | medium | low`;
+
+/**
+ * raw 텍스트에서 HANDOFF 블록을 파싱한다.
+ * @param {string} rawText
+ * @returns {object|null} 파싱된 필드 객체, 블록이 없으면 null
+ */
+export function parseHandoff(rawText) {
+  if (!rawText || typeof rawText !== "string") return null;
+
+  // P1 fix: 마지막 HANDOFF 블록을 파싱 (프롬프트 에코로 인한 중복 마커 대응)
+  const markerIdx = rawText.lastIndexOf(HANDOFF_MARKER);
+  if (markerIdx === -1) return null;
+
+  const blockStart = markerIdx + HANDOFF_MARKER.length;
+  // 다음 "---" 마커 또는 텍스트 끝까지
+  const rest = rawText.slice(blockStart);
+  const endIdx = rest.indexOf("\n---");
+  const block = endIdx === -1 ? rest : rest.slice(0, endIdx);
+
+  const lines = block.split("\n").map((l) => l.trim()).filter(Boolean);
+  const parsed = {};
+
+  for (const line of lines) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim().toLowerCase().replace(/\s+/g, "_");
+    const value = line.slice(colonIdx + 1).trim();
+    if (key && value) parsed[key] = value;
+  }
+
+  // files_changed: 쉼표 구분 → 배열
+  if (parsed.files_changed) {
+    if (parsed.files_changed === "none") {
+      parsed.files_changed = [];
+    } else {
+      parsed.files_changed = parsed.files_changed
+        .split(",")
+        .map((f) => f.trim())
+        .filter(Boolean);
+    }
+  }
+
+  return Object.keys(parsed).length > 0 ? parsed : null;
+}
+
+/**
+ * 토큰 수 추정 (rough: chars/4)
+ * @param {object} obj
+ * @returns {number}
+ */
+function estimateTokens(obj) {
+  return Math.ceil(JSON.stringify(obj).length / 4);
+}
+
+/**
+ * enum 값 검증. 유효하지 않으면 null 반환.
+ * @param {string} value
+ * @param {string[]} allowed
+ * @returns {string|null}
+ */
+function validateEnum(value, allowed) {
+  if (!value) return null;
+  const normalized = value.toLowerCase().trim();
+  return allowed.includes(normalized) ? normalized : null;
+}
+
+/**
+ * 파싱된 handoff를 검증하고 정규화한다.
+ * @param {object} parsed — parseHandoff() 결과
+ * @param {object} [context]
+ * @param {number} [context.exitCode]
+ * @param {string} [context.resultFile]
+ * @param {string[]} [context.gitDiffFiles]
+ * @returns {{ handoff: object, valid: boolean, warnings: string[] }}
+ */
+export function validateHandoff(parsed, context = {}) {
+  const warnings = [];
+  const h = { ...parsed };
+
+  // context에서 자동 삽입 (누락 필드)
+  if (!h.status && context.exitCode !== undefined) {
+    h.status = context.exitCode === 0 ? "ok" : "failed";
+    warnings.push("status: context.exitCode에서 추론");
+  }
+  if (!h.detail && context.resultFile) {
+    h.detail = context.resultFile;
+    warnings.push("detail: context.resultFile에서 추론");
+  }
+  if (!h.files_changed && context.gitDiffFiles) {
+    h.files_changed = context.gitDiffFiles;
+    warnings.push("files_changed: context.gitDiffFiles에서 추론");
+  }
+
+  // enum 검증 + 정규화
+  const enumChecks = [
+    ["status", STATUS_VALUES, "ok"],
+    ["lead_action", LEAD_ACTION_VALUES, "needs_read"],
+    ["confidence", CONFIDENCE_VALUES, "low"],
+    ["risk", RISK_VALUES, "low"],
+  ];
+
+  for (const [field, allowed, fallback] of enumChecks) {
+    if (h[field]) {
+      const validated = validateEnum(h[field], allowed);
+      if (!validated) {
+        warnings.push(`${field}: "${h[field]}" → fallback "${fallback}"`);
+        h[field] = fallback;
+      } else {
+        h[field] = validated;
+      }
+    }
+  }
+
+  // 실패 시 추가 필드 검증
+  if (h.status === "failed" || h.status === "partial") {
+    if (h.error_stage) {
+      const v = validateEnum(h.error_stage, ERROR_STAGE_VALUES);
+      if (!v) { warnings.push(`error_stage: "${h.error_stage}" invalid`); delete h.error_stage; }
+      else h.error_stage = v;
+    }
+    for (const f of ["retryable", "partial_output"]) {
+      if (h[f]) {
+        const v = validateEnum(h[f], YES_NO);
+        if (!v) { warnings.push(`${f}: "${h[f]}" invalid`); delete h[f]; }
+        else h[f] = v;
+      }
+    }
+  }
+
+  // P2a: 필수 필드 체크 (핵심 3 + 라우팅용 4)
+  const coreRequired = ["status", "lead_action", "verdict"];
+  const routingRequired = ["task", "confidence", "risk", "detail"];
+  for (const f of coreRequired) {
+    if (!h[f]) warnings.push(`missing required: ${f}`);
+  }
+  for (const f of routingRequired) {
+    if (!h[f]) warnings.push(`missing routing field: ${f}`);
+  }
+
+  // P2b: 토큰 cap + 트림
+  const tokens = estimateTokens(h);
+  if (tokens > TOKEN_HARD_CAP) {
+    h.lead_action = "needs_read";
+    // verdict 트림 (80자 + 말줄임)
+    if (h.verdict && h.verdict.length > 80) {
+      h.verdict = h.verdict.slice(0, 77) + "...";
+    }
+    // files_changed 트림 (최대 3개 + "and N more")
+    if (Array.isArray(h.files_changed) && h.files_changed.length > 3) {
+      const rest = h.files_changed.length - 3;
+      h.files_changed = [...h.files_changed.slice(0, 3), `+${rest} more`];
+    }
+    warnings.push(`token cap exceeded (${tokens} > ${TOKEN_HARD_CAP}), trimmed`);
+  }
+
+  const missingCore = coreRequired.filter((f) => !h[f]);
+  const missingRouting = routingRequired.filter((f) => !h[f]);
+  const valid = missingCore.length === 0 && missingRouting.length === 0;
+
+  return { handoff: h, valid, warnings };
+}
+
+/**
+ * 워커가 HANDOFF 블록을 생성하지 않은 경우 fallback 생성.
+ * @param {number} exitCode
+ * @param {string} resultFile
+ * @param {string} [cli]
+ * @returns {object}
+ */
+export function buildFallbackHandoff(exitCode, resultFile, cli) {
+  const ok = exitCode === 0;
+  return {
+    status: ok ? "ok" : "failed",
+    lead_action: ok ? "accept" : "retry",
+    task: "unknown",
+    files_changed: [],
+    verdict: `${cli || "worker"} completed (exit ${exitCode})`,
+    confidence: "low",
+    risk: "low",
+    detail: resultFile || "none",
+    ...(ok ? {} : {
+      error_stage: exitCode === 124 ? "timeout" : "execution",
+      retryable: exitCode === 124 ? "no" : "yes",
+    }),
+    _fallback: true,
+  };
+}
+
+/**
+ * Lead stdout용 최소 포맷 (80-120 토큰 목표)
+ * @param {object} handoff
+ * @returns {string}
+ */
+export function formatHandoffForLead(handoff) {
+  const h = handoff;
+  const files = Array.isArray(h.files_changed)
+    ? (h.files_changed.length > 0 ? h.files_changed.join(", ") : "none")
+    : (h.files_changed || "none");
+
+  const lines = [
+    `[HANDOFF] status=${h.status || "?"} action=${h.lead_action || "?"} confidence=${h.confidence || "?"}`,
+    `verdict: ${h.verdict || "(no verdict)"}`,
+    `files: ${files}`,
+    `detail: ${h.detail || "none"}`,
+  ];
+
+  if (h.status === "failed" || h.status === "partial") {
+    const parts = [];
+    if (h.error_stage) parts.push(`stage=${h.error_stage}`);
+    if (h.retryable) parts.push(`retryable=${h.retryable}`);
+    if (parts.length) lines.push(`error: ${parts.join(" ")}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * 전체 파이프라인: raw text → parse → validate → format
+ * @param {string} rawText — 워커 전체 출력
+ * @param {object} [context] — { exitCode, resultFile, gitDiffFiles }
+ * @returns {{ handoff: object, formatted: string, valid: boolean, warnings: string[], fallback: boolean }}
+ */
+export function processHandoff(rawText, context = {}) {
+  const parsed = parseHandoff(rawText);
+
+  if (!parsed) {
+    const fb = buildFallbackHandoff(
+      context.exitCode ?? 1,
+      context.resultFile || "none",
+      context.cli,
+    );
+    return {
+      handoff: fb,
+      formatted: formatHandoffForLead(fb),
+      valid: false,
+      warnings: ["HANDOFF block not found, using fallback"],
+      fallback: true,
+    };
+  }
+
+  const { handoff, valid, warnings } = validateHandoff(parsed, context);
+  return {
+    handoff,
+    formatted: formatHandoffForLead(handoff),
+    valid,
+    warnings,
+    fallback: false,
+  };
+}