triflux 4.2.8 → 4.2.9

package/hub/team/native.mjs

@@ -126,9 +126,10 @@ function getRouteTimeout(role, _mcpProfile) {
 }
 
 /**
- * v2.2 슬림 래퍼 프롬프트 생성
- * Agent spawn으로 네비게이션에 등록하되, 실제 작업은 tfx-route.sh가 수행.
- * 프롬프트 ~100 토큰 목표 (v2의 ~500 대비 80% 감소).
+ * v3 슬림 래퍼 프롬프트 생성 (async 모드)
+ * --async로 즉시 시작 → --job-wait로 내부 폴링 → --job-result로 결과 수집.
+ * Claude Code Bash 도구 600초 제한을 우회하여 scientist(24분), scientist-deep(60분) 등
+ * 장시간 워커를 안정적으로 실행한다.
  *
  * @param {'codex'|'gemini'} cli — CLI 타입
  * @param {object} opts
@@ -141,7 +142,7 @@ function getRouteTimeout(role, _mcpProfile) {
  * @param {string} [opts.mcp_profile] — MCP 프로필
  * @param {number} [opts.workerIndex] — 검색 힌트 회전에 사용할 워커 인덱스(1-based)
  * @param {string} [opts.searchTool] — 전용 검색 도구 힌트(brave-search|tavily|exa)
- * @param {number} [opts.bashTimeout] — Bash timeout(ms). 미지정 시 role/profile 기반 자동 산출.
+ * @param {number} [opts.bashTimeout] — (deprecated, async에서는 무시됨)
  * @returns {string} 슬림 래퍼 프롬프트
  */
 export function buildSlimWrapperPrompt(cli, opts = {}) {
@@ -156,23 +157,25 @@ export function buildSlimWrapperPrompt(cli, opts = {}) {
     workerIndex,
     searchTool = "",
     pipelinePhase = "",
-    bashTimeout,
   } = opts;
 
-  // role/profile 기반 timeout 산출 (기본 timeout + 60초 여유, ms 변환)
-  const bashTimeoutMs = bashTimeout ?? (getRouteTimeout(role, mcp_profile) + 60) * 1000;
-
-  // 셸 이스케이프
+  const routeTimeoutSec = getRouteTimeout(role, mcp_profile);
   const escaped = subtask.replace(/'/g, "'\\''");
   const pipelineHint = pipelinePhase
     ? `\n파이프라인 단계: ${pipelinePhase}`
     : '';
   const routeEnvPrefix = buildRouteEnvPrefix(agentName, workerIndex, searchTool);
 
-  return `실행 프로토콜 (subagent_type="${SLIM_WRAPPER_SUBAGENT_TYPE}"):
-1. Bash(command, timeout: ${bashTimeoutMs}) — 아래 명령 1회만 실행
-2. Bash 종료 후 TaskUpdate + SendMessage로 Claude Code 태스크 동기화
-3. 종료${pipelineHint}
+  // Bash 도구 timeout (모두 600초 이내)
+  const launchTimeoutMs = 15000;   // Step 1: fork + job_id 반환
+  const waitTimeoutMs = 570000;    // Step 2: 내부 폴링 (540초 대기 + 여유)
+  const resultTimeoutMs = 30000;   // Step 3: 결과 읽기
+
+  return `실행 프로토콜 (subagent_type="${SLIM_WRAPPER_SUBAGENT_TYPE}", async):
+1. --async로 백그라운드 시작 → JOB_ID 수신
+2. --job-wait로 완료 대기 (내부 15초 간격 폴링, 최대 540초)
+3. "still_running"이면 Step 2 반복, "done"이면 --job-result로 결과 수집
+4. TaskUpdate + SendMessage → 종료${pipelineHint}
 
 [HARD CONSTRAINT] 허용 도구: Bash, TaskUpdate, TaskGet, TaskList, SendMessage만 사용한다.
 Read, Edit, Write, Grep, Glob, Agent, WebSearch, WebFetch 등 다른 모든 도구 사용을 금지한다.
@@ -182,21 +185,33 @@ Read, Edit, Write, Grep, Glob, Agent, WebSearch, WebFetch 등 다른 모든 도
 gemini/codex를 직접 호출하지 마라. 반드시 tfx-route.sh를 거쳐야 한다.
 프롬프트를 파일로 저장하지 마라. tfx-route.sh가 인자로 받는다.
 
-Step 1 — Bash 실행:
-Bash(command: 'TFX_TEAM_NAME="${teamName}" TFX_TEAM_TASK_ID="${taskId}" TFX_TEAM_AGENT_NAME="${agentName}" TFX_TEAM_LEAD_NAME="${leadName}"${routeEnvPrefix} bash ${ROUTE_SCRIPT} "${role}" '"'"'${escaped}'"'"' ${mcp_profile}', timeout: ${bashTimeoutMs})
+Step 1 — Async 시작 (즉시 리턴, <1초):
+Bash(command: 'TFX_TEAM_NAME="${teamName}" TFX_TEAM_TASK_ID="${taskId}" TFX_TEAM_AGENT_NAME="${agentName}" TFX_TEAM_LEAD_NAME="${leadName}"${routeEnvPrefix} bash ${ROUTE_SCRIPT} --async "${role}" '"'"'${escaped}'"'"' ${mcp_profile} ${routeTimeoutSec}', timeout: ${launchTimeoutMs})
+→ 출력 한 줄이 JOB_ID이다. 반드시 기억하라.
+
+Step 2 — 완료 대기 (내부 폴링, 최대 540초):
+Bash(command: 'bash ${ROUTE_SCRIPT} --job-wait JOB_ID 540', timeout: ${waitTimeoutMs})
+→ 주기적 "waiting elapsed=Ns progress=NB" 출력 후 최종 상태:
+  "done" → Step 3으로
+  "timeout" 또는 "failed ..." → Step 4로 (실패 보고)
+  "still_running ..." → Step 2 반복 (같은 명령 재실행)
+
+Step 3 — 결과 수집:
+Bash(command: 'bash ${ROUTE_SCRIPT} --job-result JOB_ID', timeout: ${resultTimeoutMs})
+→ 출력이 워커 실행 결과이다.
 
-Step 2 — Claude Code 태스크 동기화 (Bash 완료 후 반드시 실행):
-exit_code=0이면:
+Step 4 — Claude Code 태스크 동기화 (반드시 실행):
+"done"이면:
   TaskUpdate(taskId: "${taskId}", status: "completed", metadata: {result: "success"})
   SendMessage(type: "message", recipient: "${leadName}", content: "완료: ${agentName}", summary: "task ${taskId} success")
-exit_code≠0이면:
-  TaskUpdate(taskId: "${taskId}", status: "completed", metadata: {result: "failed", error: "exit_code=N"})
-  SendMessage(type: "message", recipient: "${leadName}", content: "실패: ${agentName} (exit=N)", summary: "task ${taskId} failed")
+"timeout" 또는 "failed"이면:
+  TaskUpdate(taskId: "${taskId}", status: "completed", metadata: {result: "failed", error: "상태 메시지"})
+  SendMessage(type: "message", recipient: "${leadName}", content: "실패: ${agentName} (상태)", summary: "task ${taskId} failed")
 TFX_NEEDS_FALLBACK 출력 감지 시:
   TaskUpdate(taskId: "${taskId}", status: "completed", metadata: {result: "fallback", reason: "claude-native"})
   SendMessage(type: "message", recipient: "${leadName}", content: "fallback 필요: ${agentName} — claude-native 역할은 Claude Agent로 위임 필요", summary: "task ${taskId} fallback")
 
-Step 3 — TaskUpdate + SendMessage 후 즉시 종료. 추가 도구 호출 금지.`;
+Step 5 — TaskUpdate + SendMessage 후 즉시 종료. 추가 도구 호출 금지.`;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "4.2.8",
+  "version": "4.2.9",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {

package/scripts/tfx-route.sh

@@ -9,17 +9,111 @@
 #   - Gemini health check 지수 백오프 (30×1s → 5×exp)
 #   - 컨텍스트 파일 5번째 인자 지원
 #
-VERSION="2.4"
+VERSION="2.5"
 #
 # 사용법:
 #   tfx-route.sh <agent_type> <prompt> [mcp_profile] [timeout_sec] [context_file]
+#   tfx-route.sh --async <agent_type> <prompt> [mcp_profile] [timeout_sec] [context_file]
+#   tfx-route.sh --job-status <job_id>
+#   tfx-route.sh --job-result <job_id>
+#
+# --async: 백그라운드 실행, 즉시 job_id 반환 (Claude Code Bash 600초 제한 우회)
+# --job-status: running | done | timeout | failed
+# --job-result: 완료된 잡의 전체 출력
 #
 # 예시:
 #   tfx-route.sh executor "코드 구현" implement
-#   tfx-route.sh architect "아키텍처 분석" analyze '' context.md
+#   tfx-route.sh --async scientist "딥 리서치" auto 1440
+#   tfx-route.sh --job-status 1742400000-12345-9876
+#   tfx-route.sh --job-result 1742400000-12345-9876
 
 set -euo pipefail
 
+# ── Async Job 디렉토리 ──
+TFX_JOBS_DIR="${TMPDIR:-/tmp}/tfx-jobs"
+
+# ── --job-status / --job-result 핸들러 (인자 파싱 전에 처리) ──
+if [[ "${1:-}" == "--job-status" ]]; then
+  job_id="${2:?job_id 필수}"
+  job_dir="$TFX_JOBS_DIR/$job_id"
+  [[ -d "$job_dir" ]] || { echo "error: job not found"; exit 1; }
+
+  if [[ -f "$job_dir/done" ]]; then
+    exit_code=$(cat "$job_dir/exit_code" 2>/dev/null || echo 1)
+    if [[ "$exit_code" -eq 0 ]]; then
+      echo "done"
+    elif [[ "$exit_code" -eq 124 ]]; then
+      echo "timeout"
+    else
+      echo "failed"
+    fi
+  elif [[ -f "$job_dir/pid" ]]; then
+    pid=$(cat "$job_dir/pid")
+    if kill -0 "$pid" 2>/dev/null; then
+      # 진행 상황 힌트
+      local_bytes=$(wc -c < "$job_dir/stdout.log" 2>/dev/null || echo 0)
+      elapsed=$(( $(date +%s) - $(cat "$job_dir/start_time" 2>/dev/null || date +%s) ))
+      echo "running elapsed=${elapsed}s output=${local_bytes}B"
+    else
+      # 프로세스 종료됐는데 done 마커 없음 → 비정상 종료
+      echo "failed"
+    fi
+  else
+    echo "error: invalid job state"
+    exit 1
+  fi
+  exit 0
+fi
+
+if [[ "${1:-}" == "--job-result" ]]; then
+  job_id="${2:?job_id 필수}"
+  job_dir="$TFX_JOBS_DIR/$job_id"
+  [[ -d "$job_dir" ]] || { echo "error: job not found"; exit 1; }
+  [[ -f "$job_dir/done" ]] || { echo "error: job still running"; exit 1; }
+
+  cat "$job_dir/result.log" 2>/dev/null
+  exit_code=$(cat "$job_dir/exit_code" 2>/dev/null || echo 1)
+  exit "$exit_code"
+fi
+
+# ── --job-wait: 내부 폴링으로 완료 대기 (Bash 도구 호출 횟수 최소화) ──
+# 사용법: tfx-route.sh --job-wait <job_id> [max_seconds=540]
+# 출력: 주기적 "waiting elapsed=Ns" + 최종 "done"|"timeout"|"failed"|"still_running"
+if [[ "${1:-}" == "--job-wait" ]]; then
+  job_id="${2:?job_id 필수}"
+  max_wait="${3:-540}"  # 기본 540초 (9분, Bash 도구 600초 제한 이내)
+  poll_interval=15
+  job_dir="$TFX_JOBS_DIR/$job_id"
+  [[ -d "$job_dir" ]] || { echo "error: job not found"; exit 1; }
+
+  elapsed=0
+  while [[ "$elapsed" -lt "$max_wait" ]]; do
+    if [[ -f "$job_dir/done" ]]; then
+      ec=$(cat "$job_dir/exit_code" 2>/dev/null || echo 1)
+      if [[ "$ec" -eq 0 ]]; then echo "done"
+      elif [[ "$ec" -eq 124 ]]; then echo "timeout"
+      else echo "failed (exit=$ec)"
+      fi
+      exit 0
+    fi
+    sleep "$poll_interval"
+    elapsed=$((elapsed + poll_interval))
+    stderr_bytes=$(wc -c < "$job_dir/stderr.log" 2>/dev/null || echo 0)
+    echo "waiting elapsed=${elapsed}s progress=${stderr_bytes}B"
+  done
+
+  # max_wait 도달했지만 아직 실행 중
+  echo "still_running elapsed=${elapsed}s"
+  exit 0
+fi
+
+# ── --async 플래그 감지 ──
+TFX_ASYNC_MODE=0
+if [[ "${1:-}" == "--async" ]]; then
+  TFX_ASYNC_MODE=1
+  shift
+fi
+
 # ── 인자 파싱 ──
 AGENT_TYPE="${1:?에이전트 타입 필수 (executor, debugger, designer 등)}"
 PROMPT="${2:?프롬프트 필수}"
@@ -1518,4 +1612,40 @@ EOF
   return "$exit_code"
 }
 
+# ── Async 모드: 백그라운드 실행 + 즉시 job_id 반환 ──
+if [[ "$TFX_ASYNC_MODE" -eq 1 ]]; then
+  mkdir -p "$TFX_JOBS_DIR"
+  JOB_ID="$TIMESTAMP-$$-${RANDOM}"
+  JOB_DIR="$TFX_JOBS_DIR/$JOB_ID"
+  mkdir -p "$JOB_DIR"
+  echo "$AGENT_TYPE" > "$JOB_DIR/agent_type"
+  date +%s > "$JOB_DIR/start_time"
+
+  # 백그라운드 서브쉘: main 실행 → 결과 저장
+  (
+    set +e  # main 내부 에러가 exit_code 기록 전에 서브쉘을 죽이는 것 방지
+    exec > "$JOB_DIR/result.log" 2>"$JOB_DIR/stderr.log"
+    main
+    echo $? > "$JOB_DIR/exit_code"
+    touch "$JOB_DIR/done"
+  ) &
+  bg_pid=$!
+  echo "$bg_pid" > "$JOB_DIR/pid"
+
+  # 종료 감지 데몬 (main이 signal/crash로 죽어도 done 마커 생성)
+  (
+    wait "$bg_pid" 2>/dev/null
+    ec=$?
+    if [[ ! -f "$JOB_DIR/done" ]]; then
+      echo "$ec" > "$JOB_DIR/exit_code"
+      touch "$JOB_DIR/done"
+    fi
+  ) &
+  disown
+
+  # 즉시 리턴: 1초 이내에 Claude Code Bash 도구 완료
+  echo "$JOB_ID"
+  exit 0
+fi
+
 main

package/skills/tfx-multi/SKILL.md

@@ -170,7 +170,7 @@ status는 "completed"만 사용. 실패 여부는 `metadata.result`로 구분.
 
 | 항목 | 설명 |
 |------|------|
-| `scripts/tfx-route.sh` | 팀 통합 라우터 |
+| `scripts/tfx-route.sh` | 팀 통합 라우터 (v2.5: `--async`/`--job-wait`/`--job-status`/`--job-result`) |
 | `hub/team/native.mjs` | Native Teams 래퍼 (프롬프트 템플릿) |
 | `hub/pipeline/` | 파이프라인 상태 기계 (`--thorough` 모드) |
 | `tfx-auto` | one-shot 실행 오케스트레이터 |

package/skills/tfx-multi/references/agent-wrapper-rules.md

@@ -58,12 +58,25 @@ codex-worker는 반드시 tfx-route.sh를 통해 Codex에 위임하고, gemini-w
 
 리드는 워커의 Step 2, Step 4 시점에 턴 경계를 인식하고, 방향 전환/추가 지시/재실행 요청을 보낼 수 있다.
 
-## Bash timeout 동적 상속
+## Async 실행 프로토콜 (v2.5+)
 
-Bash timeout은 tfx-route.sh의 role/profile별 timeout + 60초 여유를 ms로 변환하여 동적 상속한다.
-`getRouteTimeout(role, mcpProfile)` 기준:
-- analyze/review 프로필 또는 architect/analyst 역할: 3600초
-- 그 외 기본: 1080초(18분)
+Claude Code Bash 도구는 최대 600초(10분) 하드코딩 제한이 있다.
+scientist(24분), scientist-deep(60분) 등 장시간 워커는 이 제한에 걸린다.
+
+**해결: `--async` 3단계 패턴**
+
+| 단계 | 명령 | Bash timeout | 소요 |
+|------|------|-------------|------|
+| 시작 | `tfx-route.sh --async {role} '{task}' {profile} {timeout}` | 15초 | <1초 |
+| 대기 | `tfx-route.sh --job-wait {job_id} 540` | 570초 | 최대 540초/회 |
+| 결과 | `tfx-route.sh --job-result {job_id}` | 30초 | <1초 |
+
+- `--job-wait`는 내부에서 15초 간격으로 폴링하며 `done`/`timeout`/`failed`/`still_running` 반환
+- `still_running` 시 같은 `--job-wait` 명령을 반복 (무한 반복 가능)
+- 실제 워커 timeout은 tfx-route.sh의 `timeout` 명령으로 관리 (Bash 도구와 무관)
+
+**이전 방식 (deprecated):**
+Bash timeout을 role/profile별 timeout + 60초로 설정했으나, 600초 초과 시 Bash 도구가 강제 종료했다.
 
 ## tfx-route.sh 팀 통합 동작