@triflux/remote 10.0.0-alpha.1

package/hub/workers/factory.mjs

@@ -0,0 +1,21 @@
+// 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}`);
+  }
+}

package/hub/workers/gemini-worker.mjs

@@ -0,0 +1,373 @@
+// hub/workers/gemini-worker.mjs — Gemini headless subprocess 래퍼
+// ADR-006: --output-format stream-json 기반 단발 실행 워커.
+
+import { spawn } from 'node:child_process';
+import readline from 'node:readline';
+
+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 safeJsonParse(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+
+function findLastEvent(events, predicate) {
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    if (predicate(events[index])) return events[index];
+  }
+  return null;
+}
+
+function buildGeminiArgs(options) {
+  const args = [];
+
+  if (options.model) {
+    args.push('--model', options.model);
+  }
+
+  if (options.approvalMode) {
+    args.push('--approval-mode', options.approvalMode);
+  } else if (options.yolo !== false) {
+    args.push('--yolo');
+  }
+
+  const allowedMcpServers = toStringList(options.allowedMcpServerNames);
+  if (allowedMcpServers.length) {
+    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');
+
+  return args;
+}
+
+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 isGeminiRetryable(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();
+
+  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';
+  }
+
+  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.';
+  }
+
+  return Object.freeze({
+    code: error?.code || 'GEMINI_EXECUTION_ERROR',
+    retryable,
+    attempts,
+    category,
+    recovery,
+  });
+}
+
+/**
+ * Gemini stream-json 래퍼
+ */
+export class GeminiWorker {
+  type = 'gemini';
+
+  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;
+    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,
+      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',
+    });
+
+    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',
+      command: this.command,
+      args,
+      response,
+      events,
+      resultEvent,
+      usage: resultEvent?.usage || null,
+      stdout: stdoutLines.join('\n').trim(),
+      stderr: stderrLines.join('\n').trim(),
+      exitCode,
+      exitSignal,
+      timedOut,
+      startedAtMs,
+      finishedAtMs: Date.now(),
+    };
+
+    this.lastRun = result;
+
+    if (timedOut) {
+      throw createWorkerError(`Gemini worker timed out after ${timeoutMs}ms`, {
+        code: 'ETIMEDOUT',
+        result,
+        stderr: result.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';
+  }
+
+  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),
+      });
+
+      return {
+        output: result.response,
+        exitCode: 0,
+        sessionKey: options.sessionKey || null,
+        raw: result,
+      };
+    } catch (error) {
+      return {
+        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,
+      };
+    }
+  }
+}

package/hub/workers/interface.mjs

@@ -0,0 +1,52 @@
+// hub/workers/interface.mjs — Worker 공통 인터페이스 정의
+
+/**
+ * 워커 실행 옵션
+ * @typedef {object} WorkerExecuteOptions
+ * @property {string} [cwd] - 워커 작업 디렉터리
+ * @property {string} [sessionKey] - 내부 세션 키
+ * @property {string} [threadId] - 외부에서 지정한 Codex threadId
+ * @property {boolean} [resetSession] - 기존 세션을 무시하고 새 세션 시작 여부
+ * @property {string} [model] - Codex 모델 이름
+ * @property {string} [profile] - Codex 프로필 이름
+ * @property {'untrusted'|'on-failure'|'on-request'|'never'} [approvalPolicy] - 승인 정책
+ * @property {'read-only'|'workspace-write'|'danger-full-access'} [sandbox] - 샌드박스 정책
+ * @property {Record<string, unknown>} [config] - 추가 Codex 설정
+ * @property {string} [baseInstructions] - 기본 시스템 지침
+ * @property {string} [developerInstructions] - 개발자 지침
+ * @property {string} [compactPrompt] - 컴팩션 프롬프트
+ * @property {number} [timeoutMs] - MCP 요청 타임아웃(ms)
+ */
+
+/**
+ * 워커 구조화 오류 메타데이터
+ * @typedef {object} WorkerErrorInfo
+ * @property {string} code - 오류 코드
+ * @property {boolean} retryable - 재시도 대상 여부
+ * @property {number} attempts - 실행 시도 횟수
+ * @property {'transient'|'auth'|'config'|'input'} category - 오류 분류
+ * @property {string} recovery - 권장 복구 가이드
+ */
+
+/**
+ * 워커 실행 결과
+ * @typedef {object} WorkerResult
+ * @property {string} output - 최종 텍스트 출력
+ * @property {number} exitCode - 종료 코드(0=성공)
+ * @property {string | null} [threadId] - Codex 세션 threadId
+ * @property {string | null} [sessionKey] - 내부 세션 키
+ * @property {WorkerErrorInfo} [error] - 구조화 오류 메타데이터
+ * @property {unknown} [raw] - 원본 tool call 결과
+ */
+
+/**
+ * 공통 워커 인터페이스
+ * @typedef {object} IWorker
+ * @property {(prompt: string, opts?: WorkerExecuteOptions) => Promise<WorkerResult>} execute
+ * @property {() => Promise<void>} start
+ * @property {() => Promise<void>} stop
+ * @property {() => boolean} isReady
+ * @property {string} type - 'codex' | 'gemini' | 'claude' | 'delegator'
+ */
+
+export const WORKER_TYPES = Object.freeze(['codex', 'gemini', 'claude', 'delegator']);

package/hub/workers/worker-utils.mjs

@@ -0,0 +1,104 @@
+// hub/workers/worker-utils.mjs — 워커 공통 유틸리티
+// claude-worker, gemini-worker, pipe 등에서 공유하는 순수 유틸 함수 모음.
+
+export const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
+export const DEFAULT_KILL_GRACE_MS = 1000;
+
+export function toStringList(value) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((item) => String(item ?? '').trim())
+    .filter(Boolean);
+}
+
+export function safeJsonParse(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+
+export function createWorkerError(message, details = {}) {
+  const error = new Error(message);
+  Object.assign(error, details);
+  return error;
+}
+
+function sleep(delayMs) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, Math.max(0, delayMs));
+    timer.unref?.();
+  });
+}
+
+export async function withRetry(fn, opts = {}) {
+  const {
+    maxAttempts = 3,
+    baseDelayMs = 1000,
+    maxDelayMs = 15000,
+    shouldRetry = () => true,
+  } = opts;
+
+  let lastError;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (attempt >= maxAttempts || !shouldRetry(error, attempt)) {
+        throw error;
+      }
+
+      const delay = Math.min(baseDelayMs * 2 ** (attempt - 1), maxDelayMs)
+        * (0.5 + Math.random() * 0.5);
+      await sleep(delay);
+    }
+  }
+
+  throw lastError;
+}
+
+export 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') return;
+
+  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 (value.content != null) appendTextFragments(value.content, parts);
+  if (value.message != null) appendTextFragments(value.message, parts);
+}
+
+export function extractText(value) {
+  const parts = [];
+  appendTextFragments(value, parts);
+  return parts.join('\n').trim();
+}
+
+export function terminateChild(child, killGraceMs) {
+  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 {}
+    }
+  }, killGraceMs);
+  timer.unref?.();
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@triflux/remote",
+  "version": "10.0.0-alpha.1",
+  "description": "triflux remote — team mode, psmux, MCP workers, SQLite store.",
+  "type": "module",
+  "main": "hub/index.mjs",
+  "exports": {
+    ".": "./hub/index.mjs",
+    "./hub/*": "./hub/*"
+  },
+  "engines": { "node": ">=18.0.0" },
+  "peerDependencies": {
+    "@triflux/core": "^10.0.0-alpha.1"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "better-sqlite3": "^12.6.2",
+    "systray2": "^2.1.4"
+  },
+  "files": [
+    "hub"
+  ],
+  "keywords": ["triflux", "team-mode", "psmux", "remote", "mcp-workers"],
+  "author": "tellang",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tellang/triflux.git",
+    "directory": "packages/remote"
+  }
+}