@gemus/mcp-proxy 0.1.8 → 0.1.10

package/src/proxy.mjs

@@ -1,417 +1,42 @@
 #!/usr/bin/env node
-// @gemus/mcp-proxy — local stdio<->HTTP MCP proxy for Codex desktop (Issue #1751, P1).
-//
-// Codex (stdio) <-> this proxy <-> remote gemus /api/mcp (streamable HTTP, Bearer mak_ key).
-// The proxy is a TRANSPARENT JSON-RPC passthrough (tools + resources + notifications all relay
-// untouched) that additionally TAPS execute/batch_execute to observe client-delivered image
-// backfill anchors, then at turn end backfills codex imagegen output into the planned gen-* nodes.
-// Codex does no auth for stdio MCP servers, so THIS process owns upstream auth (the user's mak_ key).
-//
-// Turn-end backfill has two triggers:
-//   • Stop hook (trusted) → loopback HTTP POST /backfill { transcript_path, thread_id } → claim path.
-//   • idle-timer fallback (untrusted hook) → salvageOnly (orphan-only). Both idempotent via seen-set.
-//
-// Validated end-to-end on 2026-07-06 (codex-cli 0.142.2, real dev /api/mcp): transparent passthrough
-// of all 12 gemus tools; codex spawns one proxy per session; real tool-calls tapped with workflowId
-// (from arguments) + turn/thread identity (from _meta.x-codex-turn-metadata). Step-0.4: plugin-bundled
-// Stop hook fires after /hooks trust. The plugin-scoped Companion forwards GEMUS_KEY from the user
-// environment, so neither the plugin config nor generated commands contain a literal key.
-// See docs/plans/1751-codex-desktop-companion.md.
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
-import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
-import http from 'node:http'
-import os from 'node:os'
-import path from 'node:path'
-import fs from 'node:fs'
-import { randomBytes } from 'node:crypto'
-import { createBackfiller, injectSteering } from './backfill.mjs'
-import { unwrapMcpContent } from '@gemus/codex-backfill-core'
-import { buildProxyUpstreamHeaders } from './mcpHeaders.mjs'
-import { createFailFast, isJsonRpcResponse } from './failFast.mjs'
-import {
-  assertGemusKey,
-  createFatalReporter,
-  createShutdownCoordinator,
-  safeEndpointLabel,
-  startProxy,
-} from './startup.mjs'
+import { pathToFileURL } from 'node:url'
 
-const KEY = process.env.GEMUS_KEY || ''
-const GEMUS_URL = process.env.GEMUS_URL || 'https://gemus.ai/api/mcp'
-const LOG = process.env.PROXY_LOG // optional debug log path
-const log = (dir, m) => {
-  if (!LOG) return
-  try {
-    fs.appendFileSync(LOG, `[${new Date().toISOString()}] ${dir} ${typeof m === 'string' ? m : JSON.stringify(m).slice(0, 1000)}\n`)
-  } catch {
-    // Debug logging is optional and must never affect proxy lifecycle.
+class ProxyUsageError extends Error {
+  constructor() {
+    super('Usage: gemus-mcp-proxy [setup]')
+    this.code = 'PROXY_USAGE'
   }
 }
 
-const reportFatal = createFatalReporter({
-  secret: KEY,
-  writeStderr: (message) => fs.writeSync(2, message),
-  writeLog: (message) => log('FATAL', message),
-})
-let shutdown
-let shutdownRequested = false
-function terminateFatally(error) {
-  reportFatal(error)
-  shutdownRequested = true
-  if (shutdown) return shutdown(1)
-  process.exit(1)
-}
-process.on('uncaughtException', (error) => { void terminateFatally(error) })
-process.on('unhandledRejection', (reason) => { void terminateFatally(reason) })
-
-try {
-  assertGemusKey(KEY)
-} catch (error) {
-  terminateFatally(error)
-}
-
-const SERVER_ORIGIN = GEMUS_URL.replace(/\/api\/mcp\/?$/, '') // core delivery appends /api/mcp itself
-const CODEX_HOME = process.env.CODEX_HOME || path.join(os.homedir(), '.codex')
-// turn-idle fallback (untrusted-hook path). Default 3min: imagegen alone runs 30-60s with NO MCP tool
-// calls, so a short idle looks like "turn ended" mid-generation and fires prematurely. A trusted Stop
-// hook fires at turn end and clears this timer, so trusted users never hit it (#1751 real-machine fix).
-const IDLE_MS = Number(process.env.PROXY_BACKFILL_IDLE_MS) || 180_000
-// footprint-0 注入交付超时（#1756 Layer 1a）。必须 ≥ 平台对 codex-imagen 回填节点的同步等待上限
-// （deriveWaitTimeoutMs('gen-image-generation')=180s，见 src/server/generation/waitTimeout.ts），否则
-// proxy 先超时 → 假失败 → orphan 回退 → 同图重复交付。240s = 180s + 余量。别调到 180s 以下。
-const INJECT_TIMEOUT_MS = Number(process.env.PROXY_INJECT_TIMEOUT_MS) || 240_000
-
-// ── footprint-0 交付注入（#1756 Layer 1a）─────────────────────────────────────────────────────────
-// 交付/orphan 不再每图新开 key-only session（connect-per-call，抢 KEY_ONLY_SESSION_CAP 槽），而是把
-// execute/canvas_edit 的 tools/call **注入到 proxy 已建好、已计入 cap 的那条 upstream 连接**上（footprint
-// 0）——即便 cap 被泄漏填满也能交付。注入用字符串 id 命名空间 `gemus-bf-*`（绝不撞 Codex 的数字 id），
-// 响应在 upstream.onmessage 里按 id 自消费、不转发给 Codex。`upstream` 在下方声明，注入在 turn 末才调，
-// 故闭包内按调用时解析、无 TDZ 问题。
-/** in-flight 注入：id(string) → { settle }。settle 幂等收敛（响应/超时/取消/关停任一先到即结算）。 */
-const pendingInjections = new Map()
-let injectSeq = 0
-
-/** 把 JSON-RPC 响应转成与 core `callGemusTool` 逐字一致的 CallGemusToolResult 形状。 */
-function interpretInjection(m) {
-  if (m?.error) return { ok: false, error: m.error.message || `MCP error ${m.error.code}` }
-  const result = m?.result
-  if (result && result.isError === true) {
-    const first = Array.isArray(result.content) ? result.content[0] : undefined
-    return { ok: false, error: (first && first.text) || 'MCP tool error' }
-  }
-  return { ok: true, result: unwrapMcpContent(result && result.content) }
-}
-
-/** @type {import('@gemus/codex-backfill-core').GemusToolCall} */
-function injectedCall(toolName, args, opts = {}) {
-  const { progressToken, signal } = opts
-  const id = `gemus-bf-${++injectSeq}`
-  const req = {
-    jsonrpc: '2.0',
-    id,
-    method: 'tools/call',
-    params: { name: toolName, arguments: args, ...(progressToken ? { _meta: { progressToken } } : {}) },
+export function validateProxyArgs(args = []) {
+  if (!Array.isArray(args) || args.length > 1 || (args.length === 1 && args[0] !== 'setup')) {
+    throw new ProxyUsageError()
   }
-  return new Promise((resolve) => {
-    const settle = (v) => {
-      clearTimeout(timer)
-      if (signal) signal.removeEventListener('abort', onAbort)
-      pendingInjections.delete(id)
-      resolve(v)
-    }
-    const onAbort = () => settle({ ok: false, error: 'aborted' })
-    const timer = setTimeout(() => settle({ ok: false, timedOut: true, error: 'inject timeout' }), INJECT_TIMEOUT_MS)
-    pendingInjections.set(id, { settle })
-    if (signal) signal.addEventListener('abort', onAbort)
-    upstream.send(req).catch((e) => settle({ ok: false, error: String(e) }))
-    log('INJECT', { id, toolName, progressToken })
-  })
 }
 
-const backfiller = createBackfiller({
-  server: SERVER_ORIGIN,
-  apiKey: KEY,
-  codexHome: CODEX_HOME,
-  call: injectedCall,
-  log: (msg, obj) => log('BACKFILL', obj ? `${msg} ${JSON.stringify(obj)}` : msg),
-})
-
-// ── turn identity + request↔response correlation ───────────────────────────────────────────────
-// Step-0.4 capture: tool-call `_meta` + Stop-hook payload both carry `turn_id` + `session_id` (no
-// thread_id). Turn state keys on turn_id; session_id locates the rollout in the idle fallback.
-/** in-flight tools/call: jsonrpc id (string) → { turnKey, name } — so the server→client response
- * (which carries no _meta) can be attributed to its turn + tool. */
-const inflight = new Map()
-/** per-turn idle timer — turn-END fallback when no Stop hook fires (untrusted). Reset on activity. */
-const idleTimers = new Map()
-let sessionId // learned from first tool-call _meta.session_id; used for the hook discovery file
-let discoveryFile // <tmpdir>/gemus-proxy-<sessionId>.json — written once sessionId is known
-
-function metaOf(msg) {
-  const meta = msg?.params?._meta?.['x-codex-turn-metadata']
-  return {
-    turnId: meta?.turn_id || meta?.turnId,
-    sessionId: meta?.session_id || meta?.sessionId,
-  }
-}
-
-function armIdleTimer(turnKey) {
-  if (!turnKey) return
-  const existing = idleTimers.get(turnKey)
-  if (existing) clearTimeout(existing)
-  const timer = setTimeout(() => {
-    idleTimers.delete(turnKey)
-    // salvageOnly fallback: turn went quiet with no Stop hook. Orphan any fresh images (never claim).
-    // seen-set makes this a no-op if a hook already backfilled this turn.
-    backfiller
-      .backfillTurn({ turnKey, rolloutPath: null, salvageOnly: true })
-      .catch((e) => log('IDLE-BACKFILL-ERR', String(e)))
-  }, IDLE_MS)
-  if (typeof timer.unref === 'function') timer.unref() // don't keep the process alive on this timer alone
-  idleTimers.set(turnKey, timer)
-}
-
-function writeDiscoveryOnce() {
-  if (discoveryFile || !sessionId || !hookPort || !hookToken) return
-  discoveryFile = path.join(os.tmpdir(), `gemus-proxy-${sessionId}.json`)
-  try {
-    fs.writeFileSync(discoveryFile, JSON.stringify({ port: hookPort, token: hookToken }))
-    log('DISCOVERY-WRITE', { discoveryFile, port: hookPort })
-  } catch (e) {
-    log('DISCOVERY-ERR', String(e))
-  }
-}
-
-// injectSteering (imported) mutates the initialize response's `instructions` to tell codex not to
-// self-forward imagegen output — the one always-on steering channel in Mode B. See backfill.mjs.
-function steerOnInit(msg) {
-  try {
-    if (injectSteering(msg)) log('STEERING-INJECTED', { instructionsLen: msg.result.instructions.length })
-  } catch (e) {
-    log('STEERING-ERR', String(e))
-  }
-}
-
-// ── taps (do not mutate the relayed messages) ──────────────────────────────────────────────────
-function tapClientToServer(msg) {
-  try {
-    if (msg?.method !== 'tools/call') return
-    const { turnId, sessionId: sid } = metaOf(msg)
-    if (sid && !sessionId) {
-      sessionId = sid
-      writeDiscoveryOnce()
-    }
-    if (turnId) armIdleTimer(turnId)
-    const id = msg.id
-    if (id === undefined || id === null) return // notifications: no response to correlate
-    const name = msg.params?.name || ''
-    inflight.set(String(id), { turnKey: turnId, name })
-    backfiller.observeCall({ jsonrpcId: id, turnKey: turnId, sessionId: sid, name, args: msg.params?.arguments || {} })
-  } catch (e) {
-    log('TAP-C2S-ERR', String(e))
-  }
-}
-
-function tapServerToClient(msg) {
-  try {
-    const id = msg?.id
-    if (id === undefined || id === null) return
-    const pending = inflight.get(String(id))
-    if (!pending) return
-    inflight.delete(String(id))
-    if (!msg.result) return // errors: nothing to observe for claim tracking
-    backfiller.observeResult({
-      jsonrpcId: id,
-      turnKey: pending.turnKey,
-      name: pending.name,
-      resultContent: msg.result?.content,
-    })
-  } catch (e) {
-    log('TAP-S2C-ERR', String(e))
-  }
-}
-
-// ── loopback Stop-hook endpoint (127.0.0.1:<random port> + per-run token) ──────────────────────
-let hookPort
-const hookToken = randomBytes(16).toString('hex')
-const hookServer = http.createServer((req, res) => {
-  if (req.method !== 'POST' || !req.url?.startsWith('/backfill')) {
-    res.writeHead(404).end()
-    return
-  }
-  let body = ''
-  req.on('data', (c) => {
-    body += c
-    if (body.length > 64 * 1024) req.destroy() // trivial DoS guard; payload is tiny JSON
-  })
-  req.on('end', () => {
-    let payload
-    try {
-      payload = JSON.parse(body)
-    } catch {
-      res.writeHead(400).end()
-      return
-    }
-    if (payload?.token !== hookToken) {
-      res.writeHead(403).end()
-      return
-    }
-    // Stop-hook payload (Step-0.4 capture): { session_id, turn_id, transcript_path, ... } — no thread_id.
-    const turnKey = payload.turn_id || payload.turnId
-    const sid = payload.session_id || payload.sessionId
-    const rolloutPath = payload.transcript_path || payload.transcriptPath || null
-    log('HOOK-BACKFILL', { turnKey, sid, rolloutPath })
-    res.writeHead(200).end('ok')
-    // A Stop hook backfilled this turn → cancel its idle-timer fallback (avoid a redundant salvage pass).
-    const timer = idleTimers.get(turnKey)
-    if (timer) { clearTimeout(timer); idleTimers.delete(turnKey) }
-    // Stop hook fires post-flush → claim path (not salvage). Fire-and-forget; never throw.
-    backfiller
-      .backfillTurn({ turnKey, sessionId: sid, rolloutPath, salvageOnly: false })
-      .catch((e) => log('HOOK-BACKFILL-ERR', String(e)))
-  })
-})
-hookServer.on('error', (error) => {
-  if (shutdownRequested) return
-  void terminateFatally(error)
-})
-hookServer.listen(0, '127.0.0.1', () => {
-  hookPort = hookServer.address().port
-  log('HOOK-SERVER', { port: hookPort })
-  writeDiscoveryOnce() // in case sessionId was already learned before listen resolved
-})
-if (typeof hookServer.unref === 'function') hookServer.unref()
-
-// ── transparent JSON-RPC passthrough (raw send/onmessage) ──────────────────────────────────────
-const stdio = new StdioServerTransport()
-
-// #2068 fail-fast: StreamableHTTPClientTransport.send() resolves before the upstream SSE result
-// arrives and only surfaces a stream death via a global, id-less `onerror` (no reconnect for POST).
-// The custom `fetch` wrapper parses each request's JSON-RPC id and, if the response stream dies
-// before that id's result crosses the wire, injects a JSON-RPC error so Codex fails in <2s instead
-// of hanging to its 300s timeout. onLost only injects to stdio — it does NOT tap: tapping here would
-// delete the proxy's `inflight` entry, so the DROP-AFTER-FAILFAST branch below could no longer let
-// backfill observe a late real result (env delivery on the still-open, idle-timed-out case).
-const failFast = createFailFast({
-  idleTimeoutMs: Number(process.env.PROXY_FAILFAST_TIMEOUT_MS) || 120_000,
-  log,
-  onLost: (id, reason) => {
-    const errObj = {
-      jsonrpc: '2.0',
-      id,
-      error: { code: -32000, message: 'Gemus upstream stream disconnected before the tool result was delivered' },
-    }
-    log('FAILFAST-INJECT', { id, reason })
-    stdio.send(errObj).catch((e) => log('ERR-stdio-send', String(e)))
-  },
-})
-
-const upstream = new StreamableHTTPClientTransport(new URL(GEMUS_URL), {
-  requestInit: { headers: buildProxyUpstreamHeaders(KEY) },
-  fetch: failFast.fetch,
-})
-
-stdio.onmessage = (m) => {
-  tapClientToServer(m)
-  log('C->G', m)
-  upstream.send(m).catch((error) => {
-    if (m?.method === 'initialize') {
-      void terminateFatally(error)
-      return
-    }
-    log('ERR-http-send', String(error))
-  })
-}
-upstream.onmessage = (m) => {
-  // footprint-0 (#1756): our injected execute/canvas_edit responses carry a `gemus-bf-*` string id.
-  // Self-consume them here (settle the pending injection) and DO NOT forward to Codex — Codex never
-  // issued these calls, so it must never see the responses.
-  if (typeof m?.id === 'string' && m.id.startsWith('gemus-bf-')) {
-    const p = pendingInjections.get(m.id)
-    if (p) p.settle(interpretInjection(m))
+export async function main(args = process.argv.slice(2)) {
+  validateProxyArgs(args)
+  if (args[0] === 'setup') {
+    const { runSetup } = await import('./setup/cli.mjs')
+    await runSetup()
     return
   }
-  // #1756 liveness heartbeat: our own `ping` pongs (gemus-ping-*) are self-consumed — Codex never
-  // issued them, so it must never see the responses.
-  if (typeof m?.id === 'string' && m.id.startsWith('gemus-ping-')) return
-  // #2068 fail-fast bookkeeping. Gate on RESPONSE only (isJsonRpcResponse) — a server→client request
-  // (elicitation/sampling) also carries an id that can collide with an in-flight tools/call id, and
-  // must be forwarded to Codex untouched, never settled/dropped.
-  if (isJsonRpcResponse(m)) {
-    if (failFast.failedIds.has(String(m.id))) {
-      // Already fail-fasted (idle timeout on a still-open stream) → Codex got the error. Still tap so
-      // backfill (#1751) observes the late real result (inflight survives — onLost didn't tap), but
-      // do NOT re-forward it to Codex (no double-send). forget() bounds failedIds.
-      tapServerToClient(m); failFast.forget(m.id); log('DROP-AFTER-FAILFAST', m.id); return
+  await import('./relay.mjs')
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const args = process.argv.slice(2)
+  main(args).catch(async (error) => {
+    if (args.length === 0) {
+      const { createFatalReporter } = await import('./startup.mjs')
+      createFatalReporter({
+        secret: process.env.GEMUS_KEY || '',
+        writeStderr: (message) => process.stderr.write(message),
+        writeLog: () => {},
+      })(error)
+    } else {
+      process.stderr.write(`${error.message}\n`)
     }
-    failFast.settle(m.id)
-  }
-  tapServerToClient(m); steerOnInit(m); log('G->C', m); stdio.send(m).catch((e) => log('ERR-stdio-send', String(e)))
-}
-
-// ── session hygiene (spike: KEY_ONLY_SESSION_CAP=3) ────────────────────────────────────────────
-// We must DELETE the upstream session or we leak a key-only slot when codex ends the conversation.
-// NOTE: transport.close() does NOT issue DELETE (it only aborts + fires onclose, streamableHttp.js:280);
-// terminateSession() sends the DELETE (:431). Call it first, then close(). Also clean up local artifacts.
-// #1756 proxy-death detection: send an MCP `ping` every 30s so the platform can tell a live proxy
-// (keeps pinging) from a dead one (hard-killed → no graceful DELETE → leaked session). This is
-// **independent of Codex tool activity**, so a proxy mid-imagegen (silent to Codex for minutes) still
-// proves liveness → the platform reclaims only genuinely-dead sessions (short floor), never a live one.
-const HEARTBEAT_MS = Number(process.env.PROXY_HEARTBEAT_MS) || 30_000
-let pingSeq = 0
-let heartbeatTimer
-function startHeartbeat() {
-  heartbeatTimer = setInterval(() => {
-    upstream.send({ jsonrpc: '2.0', id: `gemus-ping-${++pingSeq}`, method: 'ping' }).catch((e) => log('PING-ERR', String(e)))
-  }, HEARTBEAT_MS)
-  if (typeof heartbeatTimer.unref === 'function') heartbeatTimer.unref() // don't keep the process alive on this alone
-}
-
-async function cleanup() {
-  if (heartbeatTimer) clearInterval(heartbeatTimer)
-  for (const t of idleTimers.values()) clearTimeout(t)
-  idleTimers.clear()
-  // Settle any in-flight footprint-0 injections so a mid-delivery shutdown doesn't hang their awaits.
-  for (const p of pendingInjections.values()) p.settle({ ok: false, error: 'proxy shutting down' })
-  pendingInjections.clear()
-  failFast.dispose() // #2068: clear fail-fast final-safety timers
-  try { hookServer.close() } catch { /* ignore */ }
-  if (discoveryFile) { try { fs.unlinkSync(discoveryFile) } catch { /* ignore */ } }
-  try { await upstream.terminateSession() } catch { /* ignore */ }
-  try { await upstream.close() } catch { /* ignore */ }
-}
-shutdown = createShutdownCoordinator({
-  cleanup,
-  exit: (code) => process.exit(code),
-})
-function shutdownGracefully() {
-  shutdownRequested = true
-  return shutdown(0)
-}
-stdio.onclose = () => { log('stdio-close', ''); void shutdownGracefully() }
-upstream.onclose = () => { log('http-close', '') }
-stdio.onerror = (e) => log('stdio-err', String(e))
-upstream.onerror = (e) => log('http-err', String(e))
-process.on('SIGTERM', () => { void shutdownGracefully() })
-process.on('SIGINT', () => { void shutdownGracefully() })
-
-try {
-  await startProxy({
-    key: KEY,
-    upstream,
-    stdio,
-    onStarted: () => {
-      if (shutdownRequested) return
-      startHeartbeat()
-      log('STARTED', {
-        endpoint: safeEndpointLabel(GEMUS_URL),
-        hasKey: Boolean(KEY),
-        pid: process.pid,
-        idleMs: IDLE_MS,
-        heartbeatMs: HEARTBEAT_MS,
-      })
-    },
+    process.exitCode = error?.code === 'PROXY_USAGE' ? 2 : 1
   })
-} catch (error) {
-  await terminateFatally(error)
 }

package/src/proxyMessages.mjs

@@ -0,0 +1,38 @@
+const PUBLIC_MESSAGES = {
+  connection: 'Gemus upstream connection failed before a response was received',
+  http: 'Gemus upstream returned an HTTP error before the tool result was delivered',
+  stream: 'Gemus upstream stream disconnected before the tool result was delivered',
+  idle: 'Gemus upstream stream became unresponsive before the tool result was delivered',
+}
+
+const FALLBACK_MESSAGE = 'Gemus upstream failed before the tool result was delivered'
+const SAFE_CODE = /^[A-Z0-9_]{1,64}$/
+
+export function publicMessageForFailure(failure) {
+  return Object.hasOwn(PUBLIC_MESSAGES, failure?.kind)
+    ? PUBLIC_MESSAGES[failure.kind]
+    : FALLBACK_MESSAGE
+}
+
+export function createProxyFailure(id, failure) {
+  const knownKind = Object.hasOwn(PUBLIC_MESSAGES, failure?.kind)
+  const kind = knownKind ? failure.kind : 'unknown'
+  const diagnostic = { id, kind }
+
+  if (kind === 'connection') {
+    diagnostic.code = typeof failure.code === 'string' && SAFE_CODE.test(failure.code)
+      ? failure.code
+      : 'UNKNOWN'
+  } else if (kind === 'http' && Number.isInteger(failure.status)) {
+    diagnostic.status = failure.status
+  }
+
+  return {
+    response: {
+      jsonrpc: '2.0',
+      id,
+      error: { code: -32000, message: publicMessageForFailure(failure) },
+    },
+    diagnostic,
+  }
+}