triflux 9.8.2 → 9.8.3

package/hub/workers/claude-worker.mjs

@@ -3,35 +3,25 @@
 
 import { spawn } from 'node:child_process';
 import readline from 'node:readline';
-import { toStringList, safeJsonParse, createWorkerError, DEFAULT_TIMEOUT_MS, DEFAULT_KILL_GRACE_MS } from './worker-utils.mjs';
-
-function appendTextFragments(value, parts) {
-  if (value == null) return;
-  if (typeof value === 'string') {
-    const trimmed = value.trim();
-    if (trimmed) parts.push(trimmed);
-    return;
-  }
-  if (Array.isArray(value)) {
-    for (const item of value) appendTextFragments(item, parts);
-    return;
-  }
-  if (typeof value === 'object') {
-    if (typeof value.text === 'string') appendTextFragments(value.text, parts);
-    if (typeof value.result === 'string') appendTextFragments(value.result, parts);
-    if (typeof value.content === 'string' || Array.isArray(value.content) || value.content) {
-      appendTextFragments(value.content, parts);
-    }
-    if (typeof value.message === 'string' || Array.isArray(value.message) || value.message) {
-      appendTextFragments(value.message, parts);
-    }
-  }
+
+import { extractText, terminateChild, withRetry } from './worker-utils.mjs';
+
+const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
+const DEFAULT_KILL_GRACE_MS = 1000;
+
+function toStringList(value) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((item) => String(item ?? '').trim())
+    .filter(Boolean);
 }
 
-function extractText(event) {
-  const parts = [];
-  appendTextFragments(event, parts);
-  return parts.join('\n').trim();
+function safeJsonParse(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
 }
 
 function findSessionId(event) {
@@ -42,6 +32,62 @@ function findSessionId(event) {
     || null;
 }
 
+function createWorkerError(message, details = {}) {
+  const error = new Error(message);
+  Object.assign(error, details);
+  return error;
+}
+
+function normalizeRetryOptions(retryOptions) {
+  if (!retryOptions || typeof retryOptions !== 'object') {
+    return Object.freeze({});
+  }
+  return Object.freeze({ ...retryOptions });
+}
+
+function isClaudeRetryable(error) {
+  return error?.code === 'WORKER_EXIT'
+    || error?.code === 'ETIMEDOUT'
+    || error?.code === 'WORKER_STDIN_CLOSED';
+}
+
+function detectClaudeCategory(error) {
+  const combined = `${error?.message || ''}\n${error?.stderr || ''}`.toLowerCase();
+
+  if (/(unauthorized|forbidden|auth|login|token|credential|apikey|api key)/.test(combined)) {
+    return 'auth';
+  }
+  if (/unknown option|invalid option|config|permission-mode|mcp-config/.test(combined)) {
+    return 'config';
+  }
+  if (/stdin|prompt|input/.test(combined) && error?.code !== 'WORKER_STDIN_CLOSED') {
+    return 'input';
+  }
+
+  return 'transient';
+}
+
+function buildClaudeErrorInfo(error, attempts) {
+  const category = detectClaudeCategory(error);
+  let recovery = 'Restart the Claude worker session and retry the turn.';
+
+  if (category === 'auth') {
+    recovery = 'Refresh the Claude authentication state and retry.';
+  } else if (category === 'config') {
+    recovery = 'Check the Claude CLI flags, MCP configuration, and permission settings.';
+  } else if (category === 'input') {
+    recovery = 'Check the Claude request payload before retrying.';
+  }
+
+  return Object.freeze({
+    code: error?.code || 'CLAUDE_EXECUTION_ERROR',
+    retryable: isClaudeRetryable(error),
+    attempts,
+    category,
+    recovery,
+  });
+}
+
 function buildClaudeArgs(worker, options) {
   const args = [...worker.commandArgs];
 
@@ -88,6 +134,7 @@ export class ClaudeWorker {
     this.extraArgs = toStringList(options.extraArgs);
     this.timeoutMs = Number(options.timeoutMs) > 0 ? Number(options.timeoutMs) : DEFAULT_TIMEOUT_MS;
     this.killGraceMs = Number(options.killGraceMs) > 0 ? Number(options.killGraceMs) : DEFAULT_KILL_GRACE_MS;
+    this.retryOptions = normalizeRetryOptions(options.retryOptions);
     this.onEvent = typeof options.onEvent === 'function' ? options.onEvent : null;
     this.controlRequestHandler = typeof options.controlRequestHandler === 'function'
       ? options.controlRequestHandler
@@ -126,15 +173,7 @@ export class ClaudeWorker {
   }
 
   _terminateChild(child) {
-    if (!child || child.exitCode !== null || child.killed) return;
-    try { child.stdin.end(); } catch {}
-    try { child.kill(); } catch {}
-    const timer = setTimeout(() => {
-      if (child.exitCode === null) {
-        try { child.kill('SIGKILL'); } catch {}
-      }
-    }, this.killGraceMs);
-    timer.unref?.();
+    terminateChild(child, this.killGraceMs);
   }
 
   async _handleControlRequest(event) {
@@ -401,8 +440,20 @@ export class ClaudeWorker {
   }
 
   async execute(prompt, options = {}) {
+    let attempts = 0;
+
     try {
-      const result = await this.run(prompt, options);
+      const result = await withRetry(async () => {
+        attempts += 1;
+        if (attempts > 1) {
+          await this.restart();
+        }
+        return this.run(prompt, options);
+      }, {
+        ...this.retryOptions,
+        shouldRetry: (error) => isClaudeRetryable(error),
+      });
+
       return {
         output: result.response,
         exitCode: 0,
@@ -416,6 +467,7 @@ export class ClaudeWorker {
         exitCode: error.code === 'ETIMEDOUT' ? 124 : 1,
         threadId: null,
         sessionKey: options.sessionKey || this.sessionId || null,
+        error: buildClaudeErrorInfo(error, attempts || 1),
         raw: null,
       };
     }

package/hub/workers/codex-mcp.mjs

@@ -5,6 +5,8 @@ import { fileURLToPath } from 'node:url';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 
+import { withRetry } from './worker-utils.mjs';
+
 const REQUIRED_TOOLS = ['codex', 'codex-reply'];
 
 export const CODEX_MCP_TRANSPORT_EXIT_CODE = 70;
@@ -104,6 +106,60 @@ function withTimeout(promise, timeoutMs, message) {
   });
 }
 
+function normalizeRetryOptions(retryOptions) {
+  if (!retryOptions || typeof retryOptions !== 'object') {
+    return Object.freeze({});
+  }
+  return Object.freeze({ ...retryOptions });
+}
+
+function isCodexRetryable(error) {
+  return error instanceof CodexMcpTransportError
+    || error?.code === 'ETIMEDOUT'
+    || error?.cause?.code === 'ETIMEDOUT';
+}
+
+function detectWorkerCategory(error, fallbackCategory = 'transient') {
+  const combined = `${error?.message || ''}\n${error?.stderr || ''}`.toLowerCase();
+
+  if (error?.code === 'INVALID_INPUT') return 'input';
+  if (/(unauthorized|forbidden|auth|login|token|credential|apikey|api key)/i.test(combined)) {
+    return 'auth';
+  }
+  if (/(config|unknown option|invalid option|missing|필수 mcp 도구 누락)/i.test(combined)) {
+    return 'config';
+  }
+
+  return fallbackCategory;
+}
+
+function buildCodexErrorInfo(error, attempts) {
+  const retryable = isCodexRetryable(error);
+  const code = error instanceof CodexMcpTransportError
+    ? 'CODEX_TRANSPORT_ERROR'
+    : (error?.code || 'CODEX_EXECUTION_ERROR');
+  const category = detectWorkerCategory(error, retryable ? 'transient' : 'config');
+
+  let recovery = 'Review the Codex worker error output and retry after correcting the issue.';
+  if (code === 'INVALID_INPUT') {
+    recovery = 'Provide a non-empty prompt before invoking the Codex worker.';
+  } else if (retryable) {
+    recovery = 'Retry after reconnecting the Codex MCP transport.';
+  } else if (category === 'auth') {
+    recovery = 'Refresh the Codex authentication state and retry.';
+  } else if (category === 'config') {
+    recovery = 'Check the Codex MCP configuration and available tools.';
+  }
+
+  return Object.freeze({
+    code,
+    retryable,
+    attempts,
+    category,
+    recovery,
+  });
+}
+
 /**
  * Codex MCP 워커
  */
@@ -130,6 +186,7 @@ export class CodexMcpWorker {
     this.bootstrapTimeoutMs = Number.isFinite(options.bootstrapTimeoutMs)
       ? options.bootstrapTimeoutMs
       : DEFAULT_CODEX_MCP_BOOTSTRAP_TIMEOUT_MS;
+    this.retryOptions = normalizeRetryOptions(options.retryOptions);
 
     this.client = null;
     this.transport = null;
@@ -235,12 +292,11 @@ export class CodexMcpWorker {
         exitCode: CODEX_MCP_EXECUTION_EXIT_CODE,
         threadId: null,
         sessionKey: opts.sessionKey || null,
+        error: buildCodexErrorInfo({ code: 'INVALID_INPUT', message: 'prompt는 비어 있을 수 없습니다.' }, 0),
         raw: null,
       };
     }
 
-    await this.start();
-
     const sessionKey = typeof opts.sessionKey === 'string' && opts.sessionKey
       ? opts.sessionKey
       : null;
@@ -252,46 +308,84 @@ export class CodexMcpWorker {
     const threadId = typeof opts.threadId === 'string' && opts.threadId
       ? opts.threadId
       : (sessionKey ? this.getThreadId(sessionKey) : null);
+    const timeoutMs = Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : DEFAULT_CODEX_MCP_TIMEOUT_MS;
+    let attempts = 0;
+    let activeThreadId = threadId;
 
-    const toolName = pickToolName(threadId);
-    const toolArguments = toolName === 'codex-reply'
-      ? { prompt, threadId }
-      : buildCodexArguments(prompt, opts);
-
-    let rawResult;
     try {
-      rawResult = await this.client.callTool(
-        { name: toolName, arguments: toolArguments },
-        undefined,
-        { timeout: Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : DEFAULT_CODEX_MCP_TIMEOUT_MS },
-      );
+      const { rawResult, normalized } = await withRetry(async () => {
+        attempts += 1;
+        if (attempts === 1) {
+          await this.start();
+        } else {
+          await this.stop();
+          await this.start();
+        }
+
+        const toolName = pickToolName(activeThreadId);
+        const toolArguments = toolName === 'codex-reply'
+          ? { prompt, threadId: activeThreadId }
+          : buildCodexArguments(prompt, opts);
+
+        const nextRawResult = await this.client.callTool(
+          { name: toolName, arguments: toolArguments },
+          undefined,
+          { timeout: timeoutMs },
+        );
+
+        const textContent = collectTextContent(nextRawResult.content);
+        const nextNormalized = normalizeStructuredContent(nextRawResult.structuredContent, textContent);
+        activeThreadId = nextNormalized.threadId || activeThreadId;
+
+        return { rawResult: nextRawResult, normalized: nextNormalized };
+      }, {
+        ...this.retryOptions,
+        shouldRetry: (error) => isCodexRetryable(error),
+      });
+
+      if (sessionKey && normalized.threadId) {
+        this.setThreadId(sessionKey, normalized.threadId);
+      }
+
+      if (rawResult.isError) {
+        return {
+          output: normalized.content,
+          exitCode: CODEX_MCP_EXECUTION_EXIT_CODE,
+          threadId: normalized.threadId,
+          sessionKey,
+          error: buildCodexErrorInfo(
+            { code: 'CODEX_TOOL_ERROR', message: normalized.content },
+            attempts,
+          ),
+          raw: rawResult,
+        };
+      }
+
+      return {
+        output: normalized.content,
+        exitCode: 0,
+        threadId: normalized.threadId,
+        sessionKey,
+        raw: rawResult,
+      };
     } catch (error) {
+      await this.stop().catch(() => {});
       return {
         output: error instanceof Error ? error.message : String(error),
         exitCode: CODEX_MCP_EXECUTION_EXIT_CODE,
-        threadId,
+        threadId: activeThreadId,
         sessionKey,
+        error: buildCodexErrorInfo(error, attempts || 1),
         raw: null,
       };
     }
-
-    const textContent = collectTextContent(rawResult.content);
-    const normalized = normalizeStructuredContent(rawResult.structuredContent, textContent);
-
-    if (sessionKey && normalized.threadId) {
-      this.setThreadId(sessionKey, normalized.threadId);
-    }
-
-    return {
-      output: normalized.content,
-      exitCode: rawResult.isError ? CODEX_MCP_EXECUTION_EXIT_CODE : 0,
-      threadId: normalized.threadId,
-      sessionKey,
-      raw: rawResult,
-    };
   }
 }
 
+export function createCodexMcpWorker(options = {}) {
+  return new CodexMcpWorker(options);
+}
+
 function parseCliArgs(argv) {
   const options = {
     command: process.env.CODEX_BIN || 'codex',

package/hub/workers/gemini-worker.mjs

@@ -2,37 +2,26 @@
 // ADR-006: --output-format stream-json 기반 단발 실행 워커.
 
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { delimiter, extname, join } from 'node:path';
 import readline from 'node:readline';
-import { toStringList, safeJsonParse, createWorkerError, DEFAULT_TIMEOUT_MS, DEFAULT_KILL_GRACE_MS } from './worker-utils.mjs';
-
-function appendTextFragments(value, parts) {
-  if (value == null) return;
-  if (typeof value === 'string') {
-    const trimmed = value.trim();
-    if (trimmed) parts.push(trimmed);
-    return;
-  }
-  if (Array.isArray(value)) {
-    for (const item of value) appendTextFragments(item, parts);
-    return;
-  }
-  if (typeof value === 'object') {
-    if (typeof value.text === 'string') appendTextFragments(value.text, parts);
-    if (typeof value.response === 'string') appendTextFragments(value.response, parts);
-    if (typeof value.result === 'string') appendTextFragments(value.result, parts);
-    if (typeof value.content === 'string' || Array.isArray(value.content) || value.content) {
-      appendTextFragments(value.content, parts);
-    }
-    if (value.message) appendTextFragments(value.message, parts);
-  }
+
+import { extractText, terminateChild, withRetry } from './worker-utils.mjs';
+
+const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
+const DEFAULT_KILL_GRACE_MS = 1000;
+
+function toStringList(value) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((item) => String(item ?? '').trim())
+    .filter(Boolean);
 }
 
-function extractText(event) {
-  const parts = [];
-  appendTextFragments(event, parts);
-  return parts.join('\n').trim();
+function safeJsonParse(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
 }
 
 function findLastEvent(events, predicate) {
@@ -69,100 +58,61 @@ function buildGeminiArgs(options) {
   return args;
 }
 
-function resolveSpawnCommand(command, env = process.env) {
-  const raw = String(command ?? '').trim();
-  if (!raw || process.platform !== 'win32') return raw;
-
-  const pathExts = (env.PATHEXT || process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD')
-    .split(';')
-    .map((ext) => ext.trim().toLowerCase())
-    .filter(Boolean);
-  const extensions = extname(raw)
-    ? ['']
-    : [...new Set(['.cmd', '.exe', '.bat', ...pathExts, ''])];
-
-  const tryResolve = (base) => {
-    for (const ext of extensions) {
-      const candidate = `${base}${ext}`;
-      if (existsSync(candidate)) return candidate;
-    }
-    return null;
-  };
-
-  if (raw.includes('\\') || raw.includes('/')) {
-    return tryResolve(raw.replaceAll('/', '\\')) || raw;
-  }
-
-  const pathEntries = String(env.PATH || process.env.PATH || '')
-    .split(delimiter)
-    .map((entry) => entry.trim())
-    .filter(Boolean);
-
-  for (const entry of pathEntries) {
-    const resolved = tryResolve(join(entry, raw));
-    if (resolved) return resolved;
-  }
-
-  return raw;
+function createWorkerError(message, details = {}) {
+  const error = new Error(message);
+  Object.assign(error, details);
+  return error;
 }
 
-function quoteWindowsCmdArg(value) {
-  const raw = String(value ?? '');
-  if (raw.length === 0) return '""';
-
-  const escaped = raw
-    .replace(/(\\*)"/g, '$1$1\\"')
-    .replace(/(\\+)$/g, '$1$1');
-
-  return /[\s"&()<>^|]/.test(raw)
-    ? `"${escaped}"`
-    : escaped;
-}
-
-function quotePosixShellArg(value) {
-  const raw = String(value ?? '');
-  return `'${raw.replaceAll("'", `'\"'\"'`)}'`;
+function normalizeRetryOptions(retryOptions) {
+  if (!retryOptions || typeof retryOptions !== 'object') {
+    return Object.freeze({});
+  }
+  return Object.freeze({ ...retryOptions });
 }
 
-function toBashPath(value) {
-  return String(value ?? '')
-    .replace(/^([A-Za-z]):/, (_, drive) => `/${drive.toLowerCase()}`)
-    .replaceAll('\\', '/');
+function isGeminiRetryable(error) {
+  return error?.code === 'WORKER_EXIT'
+    && error?.result?.exitCode !== 0
+    && error?.result?.exitCode !== 2;
 }
 
-function buildSpawnSpec(command, args, env = process.env) {
-  const resolvedCommand = resolveSpawnCommand(command, env);
+function detectGeminiCategory(error) {
+  const combined = `${error?.message || ''}\n${error?.stderr || ''}`.toLowerCase();
 
-  if (process.platform === 'win32' && /\.(cmd|bat)$/i.test(resolvedCommand)) {
-    const commandLine = [resolvedCommand, ...args]
-      .map((part) => quoteWindowsCmdArg(part))
-      .join(' ');
-
-    return {
-      command: 'cmd.exe',
-      args: ['/d', '/s', '/c', commandLine],
-      resolvedCommand,
-    };
+  if (/(unauthorized|forbidden|auth|login|token|credential|apikey|api key)/.test(combined)) {
+    return 'auth';
+  }
+  if (error?.result?.exitCode === 2 || /expected stream-json|unknown option|invalid option|config/.test(combined)) {
+    return 'config';
+  }
+  if (error?.code === 'WORKER_EVENT_ERROR') {
+    return 'input';
   }
 
-  if (process.platform === 'win32' && !extname(resolvedCommand) && existsSync(resolvedCommand)) {
-    const bashCommand = env.TFX_BASH_BIN || env.BASH || 'bash';
-    const commandLine = [toBashPath(resolvedCommand), ...args]
-      .map((part) => quotePosixShellArg(part))
-      .join(' ');
+  return 'transient';
+}
 
-    return {
-      command: bashCommand,
-      args: ['-lc', commandLine],
-      resolvedCommand,
-    };
+function buildGeminiErrorInfo(error, attempts) {
+  const category = detectGeminiCategory(error);
+  const retryable = isGeminiRetryable(error);
+  let recovery = 'Retry the Gemini worker after correcting the reported issue.';
+
+  if (category === 'auth') {
+    recovery = 'Refresh the Gemini authentication state and retry.';
+  } else if (category === 'config') {
+    recovery = 'Check the Gemini CLI flags and worker configuration.';
+  } else if (category === 'input') {
+    recovery = 'Check the Gemini request payload and streamed event format.';
   }
 
-  return {
-    command: resolvedCommand,
-    args,
-    resolvedCommand,
-  };
+  return Object.freeze({
+    code: error?.code || 'GEMINI_EXECUTION_ERROR',
+    retryable,
+    attempts,
+    category,
+    recovery,
+  });
 }
 
 /**
@@ -183,6 +133,7 @@ export class GeminiWorker {
     this.extraArgs = toStringList(options.extraArgs);
     this.timeoutMs = Number(options.timeoutMs) > 0 ? Number(options.timeoutMs) : DEFAULT_TIMEOUT_MS;
     this.killGraceMs = Number(options.killGraceMs) > 0 ? Number(options.killGraceMs) : DEFAULT_KILL_GRACE_MS;
+    this.retryOptions = normalizeRetryOptions(options.retryOptions);
     this.onEvent = typeof options.onEvent === 'function' ? options.onEvent : null;
 
     this.state = 'idle';
@@ -213,7 +164,7 @@ export class GeminiWorker {
       return this.getStatus();
     }
     const child = this.child;
-    this._terminateChild(child);
+    terminateChild(child, this.killGraceMs);
     await new Promise((resolve) => {
       child.once('close', resolve);
       setTimeout(resolve, this.killGraceMs + 50).unref?.();
@@ -229,19 +180,6 @@ export class GeminiWorker {
     return this.getStatus();
   }
 
-  _terminateChild(child) {
-    if (!child || child.exitCode !== null || child.killed) return;
-    try { child.stdin.end(); } catch {}
-    try { child.kill(); } catch {}
-
-    const timer = setTimeout(() => {
-      if (child.exitCode === null) {
-        try { child.kill('SIGKILL'); } catch {}
-      }
-    }, this.killGraceMs);
-    timer.unref?.();
-  }
-
   async run(prompt, options = {}) {
     if (this.child) {
       throw createWorkerError('GeminiWorker is already running', { code: 'WORKER_BUSY' });
@@ -262,14 +200,13 @@ export class GeminiWorker {
         promptArgument: options.promptArgument ?? '',
       }),
     ];
-    const env = { ...this.env, ...(options.env || {}) };
-    const spawnSpec = buildSpawnSpec(this.command, args, env);
 
-    const child = spawn(spawnSpec.command, spawnSpec.args, {
+    const child = spawn(this.command, args, {
       cwd: options.cwd || this.cwd,
-      env,
+      env: { ...this.env, ...(options.env || {}) },
       stdio: ['pipe', 'pipe', 'pipe'],
       windowsHide: true,
+      shell: process.platform === 'win32',
     });
 
     this.child = child;
@@ -323,7 +260,7 @@ export class GeminiWorker {
 
     const timeout = setTimeout(() => {
       timedOut = true;
-      this._terminateChild(child);
+      terminateChild(child, this.killGraceMs);
     }, timeoutMs);
     timeout.unref?.();
 
@@ -346,13 +283,10 @@ export class GeminiWorker {
     const response = [
       extractText(resultEvent),
       ...events
-        .filter((event) => (
-          event?.type === 'assistant'
-          || (event?.type === 'message' && event?.role === 'assistant')
-        ))
+        .filter((event) => event?.type === 'message' || event?.type === 'assistant')
         .map((event) => extractText(event))
         .filter(Boolean),
-      ...stdoutLines.filter((line) => line.trim() !== '""'),
+      ...stdoutLines,
     ]
       .filter(Boolean)
       .join('\n')
@@ -360,8 +294,8 @@ export class GeminiWorker {
 
     const result = {
       type: 'gemini',
-      command: spawnSpec.resolvedCommand,
-      args: spawnSpec.args,
+      command: this.command,
+      args,
       response,
       events,
       resultEvent,
@@ -409,8 +343,17 @@ export class GeminiWorker {
   }
 
   async execute(prompt, options = {}) {
+    let attempts = 0;
+
     try {
-      const result = await this.run(prompt, options);
+      const result = await withRetry(async () => {
+        attempts += 1;
+        return this.run(prompt, options);
+      }, {
+        ...this.retryOptions,
+        shouldRetry: (error) => isGeminiRetryable(error),
+      });
+
       return {
         output: result.response,
         exitCode: 0,
@@ -422,6 +365,7 @@ export class GeminiWorker {
         output: error.stderr || error.message || 'Gemini worker failed',
         exitCode: error.code === 'ETIMEDOUT' ? 124 : 1,
         sessionKey: options.sessionKey || null,
+        error: buildGeminiErrorInfo(error, attempts || 1),
         raw: error.result || null,
       };
     }