@triflux/remote 10.1.0 → 10.26.0

package/hub/workers/factory.mjs

@@ -1,21 +1,103 @@
-// 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'           → AntigravityRouteWorker (deprecated alias)
+//   - 'antigravity'      → AntigravityRouteWorker
+//   - '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 { AntigravityRouteWorker } from "./antigravity-route-worker.mjs";
+import { CodexAppServerWorker } from "./codex-app-server-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'|'antigravity'|'agy'|'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":
+    case "antigravity":
+    case "agy":
+      return new AntigravityRouteWorker(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,62 +1,60 @@
-// hub/workers/gemini-worker.mjs — Gemini headless subprocess 래퍼
-// ADR-006: --output-format stream-json 기반 단발 실행 워커.
+// hub/workers/gemini-worker.mjs
+// Deprecated compatibility surface. Direct Gemini CLI execution is removed;
+// old imports now route through Antigravity.
 
-import { spawn } from 'node:child_process';
-import { isAbsolute } from 'node:path';
-import readline from 'node:readline';
+import { existsSync } from "node:fs";
+import { extname } from "node:path";
 
-import { extractText, terminateChild, withRetry } from './worker-utils.mjs';
-
-const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
-const DEFAULT_KILL_GRACE_MS = 1000;
+import { AntigravityRouteWorker } from "./antigravity-route-worker.mjs";
+import { withRetry } from "./worker-utils.mjs";
 
 function toStringList(value) {
   if (!Array.isArray(value)) return [];
-  return value
-    .map((item) => String(item ?? '').trim())
-    .filter(Boolean);
-}
-
-function safeJsonParse(line) {
-  try {
-    return JSON.parse(line);
-  } catch {
-    return null;
-  }
+  return value.map((item) => String(item ?? "").trim()).filter(Boolean);
 }
 
-function findLastEvent(events, predicate) {
-  for (let index = events.length - 1; index >= 0; index -= 1) {
-    if (predicate(events[index])) return events[index];
-  }
-  return null;
+/**
+ * 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}"`;
 }
 
-function buildGeminiArgs(options) {
-  const args = [];
-
-  if (options.model) {
-    args.push('--model', options.model);
+/**
+ * Windows npm shim(.cmd) spawn 문제를 해결한다.
+ */
+function buildSpawnSpec(command, args) {
+  if (process.platform !== "win32") {
+    return { command, args, shell: false };
   }
 
-  if (options.approvalMode) {
-    args.push('--approval-mode', options.approvalMode);
-  } else if (options.yolo !== false) {
-    args.push('--yolo');
+  let resolved = command;
+  if (!extname(resolved)) {
+    for (const ext of [".exe", ".cmd", ".bat"]) {
+      if (existsSync(resolved + ext)) {
+        resolved = resolved + ext;
+        break;
+      }
+    }
   }
 
-  const allowedMcpServers = toStringList(options.allowedMcpServerNames);
-  if (allowedMcpServers.length) {
-    args.push('--allowed-mcp-server-names', ...allowedMcpServers);
+  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,
+    };
   }
 
-  const extraArgs = toStringList(options.extraArgs);
-  if (extraArgs.length) args.push(...extraArgs);
-
-  args.push('--prompt', options.promptArgument ?? '');
-  args.push('--output-format', 'stream-json');
-
-  return args;
+  return { command: resolved, args, shell: false };
 }
 
 function createWorkerError(message, details = {}) {
@@ -66,49 +64,54 @@ 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;
+function isAntigravityRetryable(error) {
+  return (
+    error?.code === "WORKER_EXIT" &&
+    error?.result?.exitCode !== 0 &&
+    error?.result?.exitCode !== 2
+  );
 }
 
-function detectGeminiCategory(error) {
-  const combined = `${error?.message || ''}\n${error?.stderr || ''}`.toLowerCase();
+function detectAntigravityCategory(error) {
+  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 (
+    /(unauthorized|forbidden|auth|login|token|credential|apikey|api key)/.test(
+      combined,
+    )
+  ) {
+    return "auth";
   }
-  if (error?.code === 'WORKER_EVENT_ERROR') {
-    return 'input';
+  if (
+    error?.result?.exitCode === 2 ||
+    /unknown option|invalid option|config|route script/.test(combined)
+  ) {
+    return "config";
   }
 
-  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.';
+function buildAntigravityErrorInfo(error, attempts) {
+  const category = detectAntigravityCategory(error);
+  const retryable = isAntigravityRetryable(error);
+  let recovery = "Retry the Antigravity route worker after correcting the 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.';
+  if (category === "auth") {
+    recovery = "Refresh the Antigravity authentication state and retry.";
+  } else if (category === "config") {
+    recovery = "Check the Antigravity route worker configuration.";
   }
 
   return Object.freeze({
-    code: error?.code || 'GEMINI_EXECUTION_ERROR',
+    code: error?.code || "ANTIGRAVITY_EXECUTION_ERROR",
     retryable,
     attempts,
     category,
@@ -116,244 +119,80 @@ function buildGeminiErrorInfo(error, attempts) {
   });
 }
 
-/**
- * Gemini stream-json 래퍼
- */
-export class GeminiWorker {
-  type = 'gemini';
+export class GeminiWorker extends AntigravityRouteWorker {
+  type = "antigravity";
 
   constructor(options = {}) {
-    this.command = options.command || 'gemini';
-    this.commandArgs = toStringList(options.commandArgs || options.args);
-    this.cwd = options.cwd || process.cwd();
-    this.env = { ...process.env, ...(options.env || {}) };
-    this.model = options.model || null;
-    this.approvalMode = options.approvalMode || null;
-    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;
+    const { command, commandArgs, args, model, approvalMode, yolo, ...rest } =
+      options;
+    void commandArgs;
+    void args;
+    void model;
+    void approvalMode;
+    void yolo;
+    super(rest);
+    this.command = command || "agy";
     this.retryOptions = normalizeRetryOptions(options.retryOptions);
-    this.onEvent = typeof options.onEvent === 'function' ? options.onEvent : null;
-
-    this.state = 'idle';
-    this.child = null;
     this.lastRun = null;
   }
 
   getStatus() {
     return {
-      type: 'gemini',
-      state: this.state,
-      pid: this.child?.pid || null,
+      type: "antigravity",
+      state: this.children.size > 0 ? "running" : "idle",
+      pid: null,
       last_run_at_ms: this.lastRun?.finishedAtMs || null,
       last_exit_code: this.lastRun?.exitCode ?? null,
     };
   }
 
-  async start() {
-    if (this.state === 'stopped') {
-      this.state = 'idle';
-    }
-    return this.getStatus();
-  }
-
-  async stop() {
-    if (!this.child) {
-      this.state = 'stopped';
-      return this.getStatus();
-    }
-    const child = this.child;
-    terminateChild(child, this.killGraceMs);
-    await new Promise((resolve) => {
-      child.once('close', resolve);
-      setTimeout(resolve, this.killGraceMs + 50).unref?.();
-    });
-    this.child = null;
-    this.state = 'stopped';
-    return this.getStatus();
-  }
-
-  async restart() {
-    await this.stop();
-    this.state = 'idle';
-    return this.getStatus();
-  }
-
   async run(prompt, options = {}) {
-    if (this.child) {
-      throw createWorkerError('GeminiWorker is already running', { code: 'WORKER_BUSY' });
-    }
-
-    await this.start();
-
-    const timeoutMs = Number(options.timeoutMs) > 0 ? Number(options.timeoutMs) : this.timeoutMs;
     const startedAtMs = Date.now();
-    const args = [
-      ...this.commandArgs,
-      ...buildGeminiArgs({
-        model: options.model || this.model,
-        approvalMode: options.approvalMode || this.approvalMode,
-        yolo: options.yolo ?? this.yolo,
-        allowedMcpServerNames: options.allowedMcpServerNames || this.allowedMcpServerNames,
-        extraArgs: options.extraArgs || this.extraArgs,
-        promptArgument: options.promptArgument ?? '',
-      }),
-    ];
-
-    const child = spawn(this.command, args, {
-      cwd: options.cwd || this.cwd,
-      env: { ...this.env, ...(options.env || {}) },
-      stdio: ['pipe', 'pipe', 'pipe'],
-      windowsHide: true,
-      shell: process.platform === 'win32' && !isAbsolute(this.command),
-    });
-
-    this.child = child;
-    this.state = 'running';
-
-    const events = [];
-    const stdoutLines = [];
-    const stderrLines = [];
-    let lastErrorEvent = null;
-    let timedOut = false;
-    let exitCode = null;
-    let exitSignal = null;
-
-    const stdoutReader = readline.createInterface({
-      input: child.stdout,
-      crlfDelay: Infinity,
-    });
-    const stderrReader = readline.createInterface({
-      input: child.stderr,
-      crlfDelay: Infinity,
-    });
-
-    stdoutReader.on('line', (line) => {
-      if (!line) return;
-      const event = safeJsonParse(line);
-      if (!event) {
-        stdoutLines.push(line);
-        return;
-      }
-
-      events.push(event);
-      if (event.type === 'error') lastErrorEvent = event;
-      if (this.onEvent) {
-        try { this.onEvent(event); } catch {}
-      }
-    });
-
-    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) => {
-        exitCode = code;
-        exitSignal = signal;
-        resolve();
-      });
-    });
-
-    const timeout = setTimeout(() => {
-      timedOut = true;
-      terminateChild(child, this.killGraceMs);
-    }, timeoutMs);
-    timeout.unref?.();
-
-    child.stdin.on('error', () => {});
-    child.stdin.end(String(prompt ?? ''));
-
-    try {
-      await closePromise;
-    } finally {
-      clearTimeout(timeout);
-      stdoutReader.close();
-      stderrReader.close();
-      if (this.child === child) {
-        this.child = null;
-      }
-      this.state = 'idle';
-    }
-
-    const resultEvent = findLastEvent(events, (event) => event?.type === 'result');
-    const response = [
-      extractText(resultEvent),
-      ...events
-        .filter((event) => event?.type === 'message' || event?.type === 'assistant')
-        .map((event) => extractText(event))
-        .filter(Boolean),
-      ...stdoutLines,
-    ]
-      .filter(Boolean)
-      .join('\n')
-      .trim();
-
-    const result = {
-      type: 'gemini',
+    const result = await super.run(prompt, options);
+    const normalized = {
+      type: "antigravity",
       command: this.command,
-      args,
-      response,
-      events,
-      resultEvent,
-      usage: resultEvent?.usage || null,
-      stdout: stdoutLines.join('\n').trim(),
-      stderr: stderrLines.join('\n').trim(),
-      exitCode,
-      exitSignal,
-      timedOut,
+      args: toStringList(options.extraArgs),
+      response: result.response || result.output || "",
+      output: result.output || result.response || "",
+      stderr: result.stderr || "",
+      exitCode: result.exitCode ?? 1,
+      exitSignal: null,
+      timedOut: result.exitCode === 124,
       startedAtMs,
       finishedAtMs: Date.now(),
+      raw: result.raw || result,
     };
-
-    this.lastRun = result;
-
-    if (timedOut) {
-      throw createWorkerError(`Gemini worker timed out after ${timeoutMs}ms`, {
-        code: 'ETIMEDOUT',
-        result,
-        stderr: result.stderr,
-      });
+    this.lastRun = normalized;
+
+    if (normalized.exitCode !== 0) {
+      throw createWorkerError(
+        `Antigravity route worker exited with code ${normalized.exitCode}`,
+        {
+          code: "WORKER_EXIT",
+          result: normalized,
+          stderr: normalized.stderr,
+        },
+      );
     }
 
-    if (exitCode !== 0) {
-      throw createWorkerError(`Gemini worker exited with code ${exitCode}`, {
-        code: 'WORKER_EXIT',
-        result,
-        stderr: result.stderr,
-      });
-    }
-
-    if (lastErrorEvent) {
-      throw createWorkerError('Gemini worker emitted an error event', {
-        code: 'WORKER_EVENT_ERROR',
-        result,
-        stderr: result.stderr,
-      });
-    }
-
-    return result;
-  }
-
-  isReady() {
-    return this.state !== 'stopped';
+    return normalized;
   }
 
   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) => isAntigravityRetryable(error),
+        },
+      );
 
       return {
         output: result.response,
@@ -363,12 +202,15 @@ 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 || "Antigravity worker failed",
+        exitCode: error.code === "ETIMEDOUT" ? 124 : 1,
         sessionKey: options.sessionKey || null,
-        error: buildGeminiErrorInfo(error, attempts || 1),
+        error: buildAntigravityErrorInfo(error, attempts || 1),
         raw: error.result || null,
       };
     }
   }
 }
+
+/** @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,14 @@
  * @property {() => Promise<void>} start
  * @property {() => Promise<void>} stop
  * @property {() => boolean} isReady
- * @property {string} type - 'codex' | 'gemini' | 'claude' | 'delegator'
+ * @property {'codex'|'codex-app-server'|'gemini'|'antigravity'|'claude'|'delegator'} type
  */
 
-export const WORKER_TYPES = Object.freeze(['codex', 'gemini', 'claude', 'delegator']);
+export const WORKER_TYPES = Object.freeze([
+  "codex",
+  "codex-app-server",
+  "gemini",
+  "antigravity",
+  "claude",
+  "delegator",
+]);