@triflux/remote 10.0.1 → 10.25.1

package/hub/workers/factory.mjs

@@ -1,21 +1,100 @@
-// hub/workers/factory.mjs — Worker 생성 팩토리
-
-import { GeminiWorker } from './gemini-worker.mjs';
-import { ClaudeWorker } from './claude-worker.mjs';
-import { CodexMcpWorker } from './codex-mcp.mjs';
-import { DelegatorMcpWorker } from './delegator-mcp.mjs';
-
-export function createWorker(type, opts = {}) {
-  switch (type) {
-    case 'gemini':
-      return new GeminiWorker(opts);
-    case 'claude':
-      return new ClaudeWorker(opts);
-    case 'codex':
-      return new CodexMcpWorker(opts);
-    case 'delegator':
-      return new DelegatorMcpWorker(opts);
-    default:
-      throw new Error(`Unknown worker type: ${type}`);
-  }
-}
+// hub/workers/factory.mjs — Worker 생성 팩토리
+//
+// Supported worker types:
+//   - 'gemini'           → GeminiWorker
+//   - 'claude'           → ClaudeWorker
+//   - 'codex'            → CodexMcpWorker (default) or CodexAppServerWorker when
+//                          opts.transport === 'app-server'
+//   - 'codex-app-server' → CodexAppServerWorker (explicit alias)
+//   - 'delegator'        → DelegatorMcpWorker
+//
+// For the codex app-server transport the factory injects a default
+// `publishCallback` that forwards each envelope to `/bridge/publish` via the
+// existing `requestJson` helper. Callers can override by passing their own
+// `publishCallback` or swap the transport with `requestJsonFn`.
+
+import { ClaudeWorker } from "./claude-worker.mjs";
+import { CodexAppServerWorker } from "./codex-app-server-worker.mjs";
+import { GeminiWorker } from "./gemini-worker.mjs";
+
+/**
+ * Build a best-effort publishCallback that posts the envelope to
+ * `/bridge/publish`. Failures are swallowed so publish pressure never crashes
+ * a running worker turn.
+ * @param {(path: string, opts?: object) => Promise<unknown>} [requestJsonFn]
+ * @returns {(publishMessage: object) => Promise<void>}
+ */
+function defaultPublishCallback(requestJsonFn = null) {
+  return async (publishMessage) => {
+    try {
+      const publishRequestJson =
+        requestJsonFn || (await import("@triflux/core/hub/bridge.mjs")).requestJson;
+      await publishRequestJson("/bridge/publish", { body: publishMessage });
+    } catch {
+      // best-effort; publish failures must not crash the worker
+    }
+  };
+}
+
+/**
+ * Construct a CodexAppServerWorker with a default publishCallback wired to
+ * `requestJson('/bridge/publish', ...)` unless the caller supplied one.
+ *
+ * Issue #95 P1 #4 validation: the app-server transport does not yet implement
+ * the server-initiated approval / `tool/requestUserInput` round-trip. Any
+ * `approvalPolicy !== 'never'` would cause a codex turn to hang waiting for
+ * an approval response the worker cannot produce. Reject such configs at
+ * factory time with a clear, actionable message.
+ *
+ * @param {object} [opts]
+ */
+async function createCodexWorker(opts = {}) {
+  const { transport, requestJsonFn, publishCallback, ...rest } = opts;
+
+  if (transport === "app-server") {
+    const policy = rest.approvalPolicy;
+    if (policy !== undefined && policy !== null && policy !== "never") {
+      throw new Error(
+        `codex app-server transport currently requires approvalPolicy='never' (got '${policy}'). ` +
+          "The server-initiated approval / tool/requestUserInput round-trip is not yet implemented. " +
+          "Set approvalPolicy='never' or use transport='mcp'. " +
+          "Tracked in follow-up issue.",
+      );
+    }
+    return new CodexAppServerWorker({
+      ...rest,
+      publishCallback:
+        typeof publishCallback === "function"
+          ? publishCallback
+          : defaultPublishCallback(requestJsonFn),
+    });
+  }
+
+  // Default (and transport === 'mcp'): CodexMcpWorker with zero new deps.
+  const { CodexMcpWorker } = await import("./codex-mcp.mjs");
+  return new CodexMcpWorker(rest);
+}
+
+/**
+ * @param {'gemini'|'claude'|'codex'|'codex-app-server'|'delegator'} type
+ * @param {object} [opts]
+ * @returns {Promise<import('./interface.mjs').IWorker>}
+ */
+export async function createWorker(type, opts = {}) {
+  switch (type) {
+    case "gemini":
+      return new GeminiWorker(opts);
+    case "claude":
+      return new ClaudeWorker(opts);
+    case "codex":
+      return createCodexWorker(opts);
+    case "codex-app-server":
+      return createCodexWorker({ ...opts, transport: "app-server" });
+    case "delegator": {
+      const { DelegatorMcpWorker } = await import("./delegator-mcp.mjs");
+      return new DelegatorMcpWorker(opts);
+    }
+    default:
+      throw new Error(`Unknown worker type: ${type}`);
+  }
+}

package/hub/workers/gemini-worker.mjs

@@ -1,20 +1,68 @@
 // hub/workers/gemini-worker.mjs — Gemini headless subprocess 래퍼
 // ADR-006: --output-format stream-json 기반 단발 실행 워커.
 
-import { spawn } from 'node:child_process';
-import { isAbsolute } from 'node:path';
-import readline from 'node:readline';
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { extname } from "node:path";
+import readline from "node:readline";
 
-import { extractText, terminateChild, withRetry } from './worker-utils.mjs';
+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);
+  return value.map((item) => String(item ?? "").trim()).filter(Boolean);
+}
+
+/**
+ * Windows에서 cmd.exe에 전달할 인자를 안전하게 quoting한다.
+ * 빈 문자열은 ""로, 특수문자 포함 시 큰따옴표로 감싼다.
+ */
+function quoteWindowsCmdArg(value) {
+  const raw = String(value ?? "").replace(/[\r\n]/g, " ");
+  if (raw.length === 0) return '""';
+  if (!/[\s"()^&|<>%!]/.test(raw)) return raw;
+  const escaped = raw
+    .replace(/%/g, "%%")
+    .replace(/(\\*)"/g, '$1$1\\"')
+    .replace(/(\\+)$/g, "$1$1");
+  return `"${escaped}"`;
+}
+
+/**
+ * Windows npm shim(.cmd) spawn 문제를 해결한다.
+ * - command -v가 확장자 없는 경로를 반환하면 .exe → .cmd → .bat 순으로 탐색
+ * - .cmd/.bat는 CVE-2024-27980 이후 shell:false에서 실행 불가하므로 cmd.exe /d /s /c 경유
+ * - .exe는 직접 실행
+ * - non-Windows는 그대로 통과
+ */
+function buildSpawnSpec(command, args) {
+  if (process.platform !== "win32") {
+    return { command, args, shell: false };
+  }
+
+  let resolved = command;
+  if (!extname(resolved)) {
+    for (const ext of [".exe", ".cmd", ".bat"]) {
+      if (existsSync(resolved + ext)) {
+        resolved = resolved + ext;
+        break;
+      }
+    }
+  }
+
+  if (/\.(cmd|bat)$/i.test(resolved)) {
+    const line = [resolved, ...args].map(quoteWindowsCmdArg).join(" ");
+    return {
+      command: "cmd.exe",
+      args: ["/d", "/s", "/v:off", "/c", line],
+      shell: false,
+    };
+  }
+
+  return { command: resolved, args, shell: false };
 }
 
 function safeJsonParse(line) {
@@ -36,25 +84,25 @@ function buildGeminiArgs(options) {
   const args = [];
 
   if (options.model) {
-    args.push('--model', options.model);
+    args.push("--model", options.model);
   }
 
   if (options.approvalMode) {
-    args.push('--approval-mode', options.approvalMode);
+    args.push("--approval-mode", options.approvalMode);
   } else if (options.yolo !== false) {
-    args.push('--yolo');
+    args.push("--yolo");
   }
 
   const allowedMcpServers = toStringList(options.allowedMcpServerNames);
   if (allowedMcpServers.length) {
-    args.push('--allowed-mcp-server-names', ...allowedMcpServers);
+    args.push("--allowed-mcp-server-names", ...allowedMcpServers);
   }
 
   const extraArgs = toStringList(options.extraArgs);
   if (extraArgs.length) args.push(...extraArgs);
 
-  args.push('--prompt', options.promptArgument ?? '');
-  args.push('--output-format', 'stream-json');
+  args.push("--prompt", options.promptArgument ?? "");
+  args.push("--output-format", "stream-json");
 
   return args;
 }
@@ -66,49 +114,59 @@ function createWorkerError(message, details = {}) {
 }
 
 function normalizeRetryOptions(retryOptions) {
-  if (!retryOptions || typeof retryOptions !== 'object') {
+  if (!retryOptions || typeof retryOptions !== "object") {
     return Object.freeze({});
   }
   return Object.freeze({ ...retryOptions });
 }
 
 function isGeminiRetryable(error) {
-  return error?.code === 'WORKER_EXIT'
-    && error?.result?.exitCode !== 0
-    && error?.result?.exitCode !== 2;
+  return (
+    error?.code === "WORKER_EXIT" &&
+    error?.result?.exitCode !== 0 &&
+    error?.result?.exitCode !== 2
+  );
 }
 
 function detectGeminiCategory(error) {
-  const combined = `${error?.message || ''}\n${error?.stderr || ''}`.toLowerCase();
-
-  if (/(unauthorized|forbidden|auth|login|token|credential|apikey|api key)/.test(combined)) {
-    return 'auth';
+  const combined =
+    `${error?.message || ""}\n${error?.stderr || ""}`.toLowerCase();
+
+  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?.result?.exitCode === 2 ||
+    /expected stream-json|unknown option|invalid option|config/.test(combined)
+  ) {
+    return "config";
   }
-  if (error?.code === 'WORKER_EVENT_ERROR') {
-    return 'input';
+  if (error?.code === "WORKER_EVENT_ERROR") {
+    return "input";
   }
 
-  return 'transient';
+  return "transient";
 }
 
 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.';
+  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 Object.freeze({
-    code: error?.code || 'GEMINI_EXECUTION_ERROR',
+    code: error?.code || "GEMINI_EXECUTION_ERROR",
     retryable,
     attempts,
     category,
@@ -120,10 +178,10 @@ function buildGeminiErrorInfo(error, attempts) {
  * Gemini stream-json 래퍼
  */
 export class GeminiWorker {
-  type = 'gemini';
+  type = "gemini";
 
   constructor(options = {}) {
-    this.command = options.command || 'gemini';
+    this.command = options.command || "gemini";
     this.commandArgs = toStringList(options.commandArgs || options.args);
     this.cwd = options.cwd || process.cwd();
     this.env = { ...process.env, ...(options.env || {}) };
@@ -132,19 +190,26 @@ export class GeminiWorker {
     this.yolo = options.yolo !== false;
     this.allowedMcpServerNames = toStringList(options.allowedMcpServerNames);
     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.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.onEvent =
+      typeof options.onEvent === "function" ? options.onEvent : null;
 
-    this.state = 'idle';
+    this.state = "idle";
     this.child = null;
     this.lastRun = null;
   }
 
   getStatus() {
     return {
-      type: 'gemini',
+      type: "gemini",
       state: this.state,
       pid: this.child?.pid || null,
       last_run_at_ms: this.lastRun?.finishedAtMs || null,
@@ -153,42 +218,47 @@ export class GeminiWorker {
   }
 
   async start() {
-    if (this.state === 'stopped') {
-      this.state = 'idle';
+    if (this.state === "stopped") {
+      this.state = "idle";
     }
     return this.getStatus();
   }
 
   async stop() {
     if (!this.child) {
-      this.state = 'stopped';
+      this.state = "stopped";
       return this.getStatus();
     }
     const child = this.child;
     terminateChild(child, this.killGraceMs);
     await new Promise((resolve) => {
-      child.once('close', resolve);
+      child.once("close", resolve);
       setTimeout(resolve, this.killGraceMs + 50).unref?.();
     });
     this.child = null;
-    this.state = 'stopped';
+    this.state = "stopped";
     return this.getStatus();
   }
 
   async restart() {
     await this.stop();
-    this.state = 'idle';
+    this.state = "idle";
     return this.getStatus();
   }
 
   async run(prompt, options = {}) {
     if (this.child) {
-      throw createWorkerError('GeminiWorker is already running', { code: 'WORKER_BUSY' });
+      throw createWorkerError("GeminiWorker is already running", {
+        code: "WORKER_BUSY",
+      });
     }
 
     await this.start();
 
-    const timeoutMs = Number(options.timeoutMs) > 0 ? Number(options.timeoutMs) : this.timeoutMs;
+    const timeoutMs =
+      Number(options.timeoutMs) > 0
+        ? Number(options.timeoutMs)
+        : this.timeoutMs;
     const startedAtMs = Date.now();
     const args = [
       ...this.commandArgs,
@@ -196,22 +266,28 @@ export class GeminiWorker {
         model: options.model || this.model,
         approvalMode: options.approvalMode || this.approvalMode,
         yolo: options.yolo ?? this.yolo,
-        allowedMcpServerNames: options.allowedMcpServerNames || this.allowedMcpServerNames,
+        allowedMcpServerNames:
+          options.allowedMcpServerNames || this.allowedMcpServerNames,
         extraArgs: options.extraArgs || this.extraArgs,
-        promptArgument: options.promptArgument ?? '',
+        promptArgument: options.promptArgument ?? "",
       }),
     ];
 
-    const child = spawn(this.command, args, {
+    const {
+      command: spawnCmd,
+      args: spawnArgs,
+      shell,
+    } = buildSpawnSpec(this.command, args);
+    const child = spawn(spawnCmd, spawnArgs, {
       cwd: options.cwd || this.cwd,
       env: { ...this.env, ...(options.env || {}) },
-      stdio: ['pipe', 'pipe', 'pipe'],
+      stdio: ["pipe", "pipe", "pipe"],
       windowsHide: true,
-      shell: process.platform === 'win32' && !isAbsolute(this.command),
+      shell,
     });
 
     this.child = child;
-    this.state = 'running';
+    this.state = "running";
 
     const events = [];
     const stdoutLines = [];
@@ -230,7 +306,7 @@ export class GeminiWorker {
       crlfDelay: Infinity,
     });
 
-    stdoutReader.on('line', (line) => {
+    stdoutReader.on("line", (line) => {
       if (!line) return;
       const event = safeJsonParse(line);
       if (!event) {
@@ -239,20 +315,22 @@ export class GeminiWorker {
       }
 
       events.push(event);
-      if (event.type === 'error') lastErrorEvent = event;
+      if (event.type === "error") lastErrorEvent = event;
       if (this.onEvent) {
-        try { this.onEvent(event); } catch {}
+        try {
+          this.onEvent(event);
+        } catch {}
       }
     });
 
-    stderrReader.on('line', (line) => {
+    stderrReader.on("line", (line) => {
       if (!line) return;
       stderrLines.push(line);
     });
 
     const closePromise = new Promise((resolve, reject) => {
-      child.once('error', reject);
-      child.once('close', (code, signal) => {
+      child.once("error", reject);
+      child.once("close", (code, signal) => {
         exitCode = code;
         exitSignal = signal;
         resolve();
@@ -265,8 +343,8 @@ export class GeminiWorker {
     }, timeoutMs);
     timeout.unref?.();
 
-    child.stdin.on('error', () => {});
-    child.stdin.end(String(prompt ?? ''));
+    child.stdin.on("error", () => {});
+    child.stdin.end(String(prompt ?? ""));
 
     try {
       await closePromise;
@@ -277,32 +355,37 @@ export class GeminiWorker {
       if (this.child === child) {
         this.child = null;
       }
-      this.state = 'idle';
+      this.state = "idle";
     }
 
-    const resultEvent = findLastEvent(events, (event) => event?.type === 'result');
+    const resultEvent = findLastEvent(
+      events,
+      (event) => event?.type === "result",
+    );
     const response = [
       extractText(resultEvent),
       ...events
-        .filter((event) => event?.type === 'message' || event?.type === 'assistant')
+        .filter(
+          (event) => event?.type === "message" || event?.type === "assistant",
+        )
         .map((event) => extractText(event))
         .filter(Boolean),
       ...stdoutLines,
     ]
       .filter(Boolean)
-      .join('\n')
+      .join("\n")
       .trim();
 
     const result = {
-      type: 'gemini',
+      type: "gemini",
       command: this.command,
       args,
       response,
       events,
       resultEvent,
       usage: resultEvent?.usage || null,
-      stdout: stdoutLines.join('\n').trim(),
-      stderr: stderrLines.join('\n').trim(),
+      stdout: stdoutLines.join("\n").trim(),
+      stderr: stderrLines.join("\n").trim(),
       exitCode,
       exitSignal,
       timedOut,
@@ -314,23 +397,27 @@ export class GeminiWorker {
 
     if (timedOut) {
       throw createWorkerError(`Gemini worker timed out after ${timeoutMs}ms`, {
-        code: 'ETIMEDOUT',
+        code: "ETIMEDOUT",
         result,
         stderr: result.stderr,
       });
     }
 
     if (exitCode !== 0) {
-      throw createWorkerError(`Gemini worker exited with code ${exitCode}`, {
-        code: 'WORKER_EXIT',
+      // Build a descriptive message when stderr is empty to aid debugging
+      const errMsg = result.stderr
+        ? `Gemini worker exited with code ${exitCode}`
+        : `Gemini worker exited with code ${exitCode} (stderr empty, signal=${exitSignal ?? "none"}, events=${events.length}, stdout=${result.stdout.length}B)`;
+      throw createWorkerError(errMsg, {
+        code: "WORKER_EXIT",
         result,
         stderr: result.stderr,
       });
     }
 
     if (lastErrorEvent) {
-      throw createWorkerError('Gemini worker emitted an error event', {
-        code: 'WORKER_EVENT_ERROR',
+      throw createWorkerError("Gemini worker emitted an error event", {
+        code: "WORKER_EVENT_ERROR",
         result,
         stderr: result.stderr,
       });
@@ -340,20 +427,23 @@ export class GeminiWorker {
   }
 
   isReady() {
-    return this.state !== 'stopped';
+    return this.state !== "stopped";
   }
 
   async execute(prompt, options = {}) {
     let attempts = 0;
 
     try {
-      const result = await withRetry(async () => {
-        attempts += 1;
-        return this.run(prompt, options);
-      }, {
-        ...this.retryOptions,
-        shouldRetry: (error) => isGeminiRetryable(error),
-      });
+      const result = await withRetry(
+        async () => {
+          attempts += 1;
+          return this.run(prompt, options);
+        },
+        {
+          ...this.retryOptions,
+          shouldRetry: (error) => isGeminiRetryable(error),
+        },
+      );
 
       return {
         output: result.response,
@@ -363,8 +453,8 @@ export class GeminiWorker {
       };
     } catch (error) {
       return {
-        output: error.stderr || error.message || 'Gemini worker failed',
-        exitCode: error.code === 'ETIMEDOUT' ? 124 : 1,
+        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,
@@ -372,3 +462,6 @@ export class GeminiWorker {
     }
   }
 }
+
+/** @visibleForTesting — 테스트 전용 export. 외부 소비 금지. */
+export { buildSpawnSpec, quoteWindowsCmdArg };

package/hub/workers/interface.mjs

@@ -16,6 +16,21 @@
  * @property {string} [developerInstructions] - 개발자 지침
  * @property {string} [compactPrompt] - 컴팩션 프롬프트
  * @property {number} [timeoutMs] - MCP 요청 타임아웃(ms)
+ * @property {'mcp'|'app-server'} [transport] - Codex 전송 계층 선택 (팩토리 전용)
+ */
+
+/**
+ * Codex 워커 생성 옵션 (팩토리 레벨)
+ * @typedef {object} CodexWorkerFactoryOptions
+ * @property {'mcp'|'app-server'} [transport] - 'mcp' (기본) 또는 'app-server'
+ * @property {(publishMessage: object) => void|Promise<void>} [publishCallback] - app-server 전용 publish 후크
+ * @property {(path: string, opts?: object) => Promise<unknown>} [requestJsonFn] - 테스트/리팩터용 requestJson 주입
+ * @property {string} [command] - codex 실행 바이너리 경로
+ * @property {string[]} [args] - codex CLI 인자 배열
+ * @property {string} [cwd] - 워커 작업 디렉터리
+ * @property {Record<string, string>} [env] - 추가 환경 변수
+ * @property {{ name: string, version: string }} [clientInfo] - MCP/JSON-RPC clientInfo
+ * @property {number} [bootstrapTimeoutMs] - 핸드셰이크 타임아웃(ms)
  */
 
 /**
@@ -46,7 +61,13 @@
  * @property {() => Promise<void>} start
  * @property {() => Promise<void>} stop
  * @property {() => boolean} isReady
- * @property {string} type - 'codex' | 'gemini' | 'claude' | 'delegator'
+ * @property {'codex'|'codex-app-server'|'gemini'|'claude'|'delegator'} type
  */
 
-export const WORKER_TYPES = Object.freeze(['codex', 'gemini', 'claude', 'delegator']);
+export const WORKER_TYPES = Object.freeze([
+  "codex",
+  "codex-app-server",
+  "gemini",
+  "claude",
+  "delegator",
+]);