@gemus/mcp-proxy 0.1.8 → 0.1.10

package/README.md

@@ -9,11 +9,49 @@ and `docs/architecture/agent architecture/codex-desktop-companion.md`.
 
 ## Status: implemented
 
-`src/proxy.mjs` is the production passthrough, execute-tap, and deterministic image-backfill
-companion. A trusted Stop hook triggers `generated_images`/rollout discovery; `ExecuteClaimTracker`
-then delivers an unambiguous image to its planned node or conservatively creates an orphan
-`image-upload`. MCP initialization advertises the shared Codex capability contract used by the
-server blueprint policy.
+`src/proxy.mjs` is the executable router: `setup` loads the isolated installer, while no arguments
+load `src/relay.mjs`. The relay is the production passthrough, execute-tap, and deterministic
+image-backfill companion. A trusted Stop hook triggers `generated_images`/rollout discovery;
+`ExecuteClaimTracker` then delivers an unambiguous image to its planned node or conservatively
+creates an orphan `image-upload`. MCP initialization advertises the shared Codex capability
+contract used by the server blueprint policy.
+
+## Upstream connection reliability (#2328)
+
+The proxy uses one owned Undici `Agent` for all upstream MCP traffic. By default its TCP
+address-family racing policy sets `autoSelectFamily: true` with a
+`PROXY_CONNECT_ATTEMPT_TIMEOUT_MS=1000` per-address-family attempt window. An operator may set a
+positive numeric override; invalid, empty, and non-positive values fall back to `1000`, while
+values below `10` ms clamp to `10` ms. The transport's request method, body, and auth headers are
+preserved; the proxy adds only that owned dispatcher.
+
+This is a connection-attempt policy, not an MCP retry policy. For a post-start request, a rejected
+`POST` before response headers produces one request only: the affected JSON-RPC id receives `-32000`
+with `Gemus upstream connection failed before a response was received`. The raw network reason is
+never returned to Codex. During `initialize`, the same classification writes one sanitized fatal
+diagnostic and exits non-zero. Once an SSE response has started, a body that ends before its result
+remains the distinct #2068 failure:
+`Gemus upstream stream disconnected before the tool result was delivered`.
+
+On graceful or fatal shutdown, the proxy bounds session `DELETE`, then transport close, before it
+closes the owned Agent. Each stage has a 2-second bound; an Agent that does not close in its bound
+has its retained per-origin dispatchers force-destroyed before the Agent is destroyed. Repeated
+shutdown signals share the same cleanup. See the [transport reliability
+runbook](../../docs/operations/mcp-transport-reliability.md) for the network boundaries and the
+[Companion architecture](../../docs/architecture/agent%20architecture/codex-desktop-companion.md)
+for the request path.
+
+## Release gate (#2330)
+
+`@gemus/mcp-proxy@0.1.9` was published and verified on 2026-07-28. Release Issue
+[#2330](https://github.com/Gemus-AI/Gemus/issues/2330) rolls the plugin to exact `0.1.9`, forwards
+`PROXY_CONNECT_ATTEMPT_TIMEOUT_MS`, and bumps the plugin contract to 0.1.12. After that change
+merges, the remaining gate is to verify the public mirror, refresh the installed Codex plugin
+cache, and run repeated fresh-process ESA and, when available, isolated direct-domain smoke tests.
+
+That public `0.1.9` package is immutable and transport-only: it does not contain the one-command
+setup added by #2324. The setup release therefore advances to `@gemus/mcp-proxy@0.1.10`, with
+plugin contract `0.1.13`; the historical #2328/#2330 release remains `0.1.9`/`0.1.12`.
 
 ## What was validated end-to-end (2026-07-06, codex-cli 0.142.2 → local dev `/api/mcp`)
 
@@ -34,24 +72,40 @@ server blueprint policy.
 
 ## Companion setup and migration (Codex desktop)
 
-The plugin owns the non-secret process contract: exact `@gemus/mcp-proxy@0.1.8`,
+The plugin owns the non-secret process contract: exact `@gemus/mcp-proxy@0.1.10`,
 `startup_timeout_sec = 60`, `tool_timeout_sec = 300`, and a default-disabled rollout. The user
-environment owns `GEMUS_KEY` and optional `GEMUS_URL`; the public plugin and generated commands
-never contain their values.
+environment owns `GEMUS_KEY`, optional `GEMUS_URL`, and optional
+`PROXY_CONNECT_ATTEMPT_TIMEOUT_MS`; the public plugin and generated commands never contain their
+values.
+
+For the production Gemus service, use this Windows/macOS setup command; it is safe to rerun:
+
+```bash
+npx -y @gemus/mcp-proxy@0.1.10 setup
+```
+
+It securely prompts for the key, reconciles the marketplace/plugin, migrates legacy Gemus config,
+enables the Companion, and preserves a backup when it changes `config.toml`. Fully quit and restart
+Codex when it finishes, then open a new task and run `/hooks` to trust the Gemus Stop hook.
+
+The public setup command, shell history, and setup diagnostics remain key-free. On macOS, the
+short-lived `launchctl setenv` child necessarily receives the key in its argv.
 
 Environment ownership and lifetime:
 
-- **Windows / PowerShell:** persist the key in the Windows user environment and refresh the current
-  process.
+- **Windows / PowerShell:** persist the key in the Windows user environment scope. Fully quit and
+  restart Codex so it receives the updated environment.
 - **macOS:** If changing login context, sign out and back in first; rerun the `launchctl setenv`
-  setup in the new login session; then fully quit and restart Codex and open a new task.
+  setup in the new login session; the value lasts for the current login session only. Then fully quit
+  and restart Codex and open a new task.
 - **Linux:** export the key and launch Codex from the same terminal; no universal desktop-session
   inheritance is assumed.
 
-Companion and direct modes are mutually exclusive. The canonical new-user and legacy migration flow
-is:
+Companion and direct modes are mutually exclusive. The following advanced manual fallback is for
+Linux, self-hosted `GEMUS_URL`, or troubleshooting when the production one-command setup is not
+applicable:
 
-1. Set `GEMUS_KEY` in the user environment.
+1. Set `GEMUS_KEY` in the user environment (and optional `GEMUS_URL` for self-hosted/development).
 2. Remove any legacy global server (`codex mcp remove gemus`; not-found is harmless).
 3. Install with `codex plugin marketplace add Gemus-AI/gemus-codex-plugin`, then
    `codex plugin add gemus@gemus`. Existing users refresh the marketplace snapshot and replace the
@@ -69,7 +123,7 @@ is:
    enabled = true
    ```
 
-5. Restart Codex and open a new task, then use `/hooks` to trust the Stop hook separately.
+5. Fully quit and restart Codex, open a new task, then trust the Gemus Stop hook with `/hooks`.
 
 Intentional direct HTTP/OAuth users keep their global direct server and leave the plugin Companion
 disabled:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemus/mcp-proxy",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Local stdio<->HTTP MCP proxy for Codex desktop: transparent passthrough + execute tap + imagegen backfill (Issue #1751, P1).",
   "type": "module",
   "bin": {
@@ -25,13 +25,15 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "undici": "^6.28.0",
     "@gemus/codex-backfill-core": "0.1.3"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=18.17"
   },
   "files": [
-    "src/",
+    "src/*.mjs",
+    "src/setup/*.mjs",
     "README.md"
   ],
   "license": "MIT",

package/src/failFast.mjs

@@ -93,11 +93,24 @@ export function createSseIdScanner() {
   }
 }
 
+/** Extract an allowlisted network error code without exposing the raw error text. */
+function failureCode(error) {
+  let current = error
+  for (let depth = 0; depth < 8 && current && typeof current === 'object'; depth++) {
+    if (typeof current.code === 'string') {
+      const code = current.code.toUpperCase()
+      if (/^[A-Z0-9_]{1,64}$/.test(code)) return code
+    }
+    current = current.cause
+  }
+  return 'UNKNOWN'
+}
+
 /**
  * Build the fail-fast fetch wrapper + settle/dispose controls.
  *
  * @param {object} opts
- * @param {(id:any, reason:string)=>void} opts.onLost  called once per lost id (must be idempotent-safe on caller side)
+ * @param {(id:any, failure:{kind:string, code?:string, status?:number})=>void} opts.onLost  called once per lost id (must be idempotent-safe on caller side)
  * @param {number} [opts.idleTimeoutMs]  IDLE backstop reset on every upstream byte (incl. server
  *   heartbeats every ~12s), so it trips ONLY on a genuinely silent/zombie connection — never on a
  *   healthy-but-slow tool. Must be < Codex 300s; default 120_000.
@@ -117,7 +130,7 @@ export function createFailFast(opts) {
   const failedIds = new Set()
 
   function armTimer(entry, id) {
-    entry.timer = setTimeout(() => lose(id, 'proxy idle timeout (no upstream bytes)'), idleTimeoutMs)
+    entry.timer = setTimeout(() => lose(id, { kind: 'idle' }), idleTimeoutMs)
     if (typeof entry.timer.unref === 'function') entry.timer.unref()
   }
 
@@ -150,15 +163,15 @@ export function createFailFast(opts) {
     failedIds.delete(String(id))
   }
 
-  function lose(id, reason) {
+  function lose(id, failure) {
     const key = String(id)
     if (!inFlight.has(key)) return // already settled or already lost
     settle(id)
     failedIds.add(key)
     // Bound the set: disconnect-case entries never see a late result to forget(), so cap FIFO.
     if (failedIds.size > FAILED_IDS_CAP) failedIds.delete(failedIds.values().next().value)
-    log('FAILFAST', { id, reason })
-    onLost(id, reason)
+    log('FAILFAST', { id, ...failure })
+    onLost(id, failure)
   }
 
   function observeAndForward(body, codexIds) {
@@ -168,7 +181,7 @@ export function createFailFast(opts) {
     const onEnd = () => {
       if (ended) return
       ended = true
-      for (const id of codexIds) lose(id, 'upstream stream closed before result')
+      for (const id of codexIds) lose(id, { kind: 'stream' })
     }
     return new ReadableStream({
       async pull(controller) {
@@ -218,7 +231,7 @@ export function createFailFast(opts) {
       codexIds = parseRequestIds(init).filter(isCodexOriginated)
       for (const id of codexIds) register(id)
     } catch (e) {
-      log('FAILFAST-WRAP-ERR', String(e))
+      log('FAILFAST-WRAP-ERR', { code: failureCode(e) })
       codexIds = []
     }
 
@@ -229,7 +242,7 @@ export function createFailFast(opts) {
       res = await realFetch(url, init)
     } catch (e) {
       // Connection failed before any response (DNS / TLS / RST) — fail fast, don't wait 270s.
-      for (const id of codexIds) lose(id, `upstream fetch failed: ${e}`)
+      for (const id of codexIds) lose(id, { kind: 'connection', code: failureCode(e) })
       throw e // preserve the SDK's existing onerror/logging path (no re-fetch)
     }
 
@@ -241,7 +254,7 @@ export function createFailFast(opts) {
       if (!res.ok) {
         // Non-SSE HTTP error (404 session-gone / 403 / 429 / …). send() throws before onmessage,
         // and that rejection is swallowed by upstream.send().catch — so nothing ever settles the id.
-        for (const id of codexIds) lose(id, `upstream HTTP ${res.status}`)
+        for (const id of codexIds) lose(id, { kind: 'http', status: res.status })
         return res
       }
       const ct = res.headers.get('content-type') || ''
@@ -252,7 +265,7 @@ export function createFailFast(opts) {
         headers: res.headers,
       })
     } catch (e) {
-      log('FAILFAST-WRAP-ERR', String(e))
+      log('FAILFAST-WRAP-ERR', { code: failureCode(e) })
       return res
     }
   }