@gemus/mcp-proxy 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemus/mcp-proxy",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Local stdio<->HTTP MCP proxy for Codex desktop: transparent passthrough + execute tap + imagegen backfill (Issue #1751, P1).",
   "type": "module",
   "bin": {
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@gemus/codex-backfill-core": "0.1.0"
+    "@gemus/codex-backfill-core": "0.1.1"
   },
   "engines": {
     "node": ">=18"

package/src/__tests__/backfill.test.ts

@@ -11,6 +11,7 @@ const mocks = vi.hoisted(() => ({
   addImageToCanvas: vi.fn(),
   readRollout: vi.fn(),
   findRolloutFile: vi.fn(),
+  readGeneratedImageFiles: vi.fn(),
 }))
 
 vi.mock('@gemus/codex-backfill-core', async (importOriginal) => {
@@ -21,6 +22,7 @@ vi.mock('@gemus/codex-backfill-core', async (importOriginal) => {
     addImageToCanvas: mocks.addImageToCanvas,
     readRollout: mocks.readRollout,
     findRolloutFile: mocks.findRolloutFile,
+    readGeneratedImageFiles: mocks.readGeneratedImageFiles,
   }
 })
 
@@ -71,6 +73,8 @@ beforeEach(() => {
   mocks.addImageToCanvas.mockReset().mockResolvedValue({ ok: true, entityId: 'agent_x' })
   mocks.readRollout.mockReset().mockReturnValue('')
   mocks.findRolloutFile.mockReset().mockReturnValue('/fake/rollout.jsonl')
+  // Default: generated_images unavailable → backfill falls back to the rollout source (existing tests).
+  mocks.readGeneratedImageFiles.mockReset().mockReturnValue({ available: false, images: [] })
 })
 
 describe('normalizeToolName (tap → tracker)', () => {
@@ -255,3 +259,84 @@ describe('backfillTurn — idempotency + guards', () => {
     expect(mocks.addImageToCanvas).not.toHaveBeenCalled()
   })
 })
+
+describe('backfillTurn — footprint-0 call passthrough + timeout semantics (#1756 Layer 1a)', () => {
+  it('threads the injected `call` into deliver AND orphan (footprint-0)', async () => {
+    const call = vi.fn()
+    const bf = createBackfiller({
+      server: 'http://localhost:3000',
+      apiKey: 'mak_test',
+      codexHome: '/fake/.codex',
+      call,
+    })
+    observeExecuteAnchor(bf, 1, 't1', 's1', 'wf_real', 'nodeA')
+    mocks.readRollout.mockReturnValue(rollout([IMG_A]))
+    mocks.deliverImageToNode.mockResolvedValue({ ok: false, code: 'ALREADY_COMPLETED' }) // force orphan fallback
+
+    await bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: '/x', salvageOnly: false })
+
+    expect(mocks.deliverImageToNode.mock.calls[0][0]).toMatchObject({ call })
+    expect(mocks.addImageToCanvas.mock.calls[0][0]).toMatchObject({ call })
+  })
+
+  it('a timed-out deliver leaves the image FRESH — no orphan, not marked seen (no duplicate)', async () => {
+    const bf = makeBackfiller()
+    observeExecuteAnchor(bf, 1, 't1', 's1', 'wf_real', 'nodeA')
+    mocks.readRollout.mockReturnValue(rollout([IMG_A]))
+    // deliver times out → result unknown; the platform job may still land, so we must NOT orphan.
+    mocks.deliverImageToNode.mockResolvedValue({ ok: false, timedOut: true, error: 'inject timeout' })
+
+    const r1 = await bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: '/x', salvageOnly: false })
+    expect(r1).toEqual({ delivered: 0, orphaned: 0, dropped: 0 })
+    expect(mocks.addImageToCanvas).not.toHaveBeenCalled() // NO orphan on timeout
+
+    // Image stayed fresh (not seen): a later Stop-hook pass can still deliver it once the job lands.
+    mocks.deliverImageToNode.mockResolvedValue({ ok: true, status: 'processing' })
+    const r2 = await bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: '/x', salvageOnly: false })
+    expect(r2.delivered).toBe(1)
+  })
+})
+
+describe('backfillTurn — Layer 2 file byte source (#1756)', () => {
+  it('uses generated_images when available and does NOT read the rollout', async () => {
+    const bf = makeBackfiller()
+    observeExecuteAnchor(bf, 1, 't1', 's1', 'wf_real', 'nodeA')
+    // generated_images available with one fresh image → file source wins, rollout untouched.
+    mocks.readGeneratedImageFiles.mockReturnValue({
+      available: true,
+      images: [{ callId: 'ig_a', base64: 'iVBORw0KGgoAAAA1', mimeType: 'image/png' }],
+    })
+
+    const r = await bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: '/x', salvageOnly: false })
+
+    expect(mocks.readGeneratedImageFiles).toHaveBeenCalled()
+    expect(mocks.readRollout).not.toHaveBeenCalled() // file source is authoritative when available
+    expect(r.delivered).toBe(1)
+    expect(mocks.deliverImageToNode.mock.calls[0][0]).toMatchObject({ nodeId: 'nodeA', image: { callId: 'ig_a' } })
+  })
+
+  it('available but empty → no delivery, and does NOT fall back to rollout (mtime guard preserved)', async () => {
+    const bf = makeBackfiller()
+    observeExecuteAnchor(bf, 1, 't1', 's1', 'wf_real', 'nodeA')
+    mocks.readGeneratedImageFiles.mockReturnValue({ available: true, images: [] })
+    // Even though the rollout has an image, availability=true must lock us to the (empty) file source.
+    mocks.readRollout.mockReturnValue(rollout([IMG_A]))
+
+    const r = await bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: '/x', salvageOnly: false })
+
+    expect(mocks.readRollout).not.toHaveBeenCalled()
+    expect(r).toEqual({ delivered: 0, orphaned: 0, dropped: 0 })
+  })
+
+  it('unavailable → falls back to rollout-scrape (older codex)', async () => {
+    const bf = makeBackfiller()
+    observeExecuteAnchor(bf, 1, 't1', 's1', 'wf_real', 'nodeA')
+    mocks.readGeneratedImageFiles.mockReturnValue({ available: false, images: [] })
+    mocks.readRollout.mockReturnValue(rollout([IMG_A]))
+
+    const r = await bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: '/x', salvageOnly: false })
+
+    expect(mocks.readRollout).toHaveBeenCalledWith('/x')
+    expect(r.delivered).toBe(1)
+  })
+})

package/src/backfill.mjs

@@ -16,6 +16,10 @@
 // a later trigger no-ops. salvageOnly NEVER calls claim() — mirrors bridge salvage semantics (图不丢, 不认领).
 import * as core from '@gemus/codex-backfill-core'
 
+// #1756 Layer 2 mtime cutoff：只认本进程启动后落盘的 generated_images 文件，防 proxy 重启后把该
+// session 历史图当 fresh 重复交付（session_id 跨 resume 复用、seen 是进程内存）。模块加载≈proxy 启动。
+const procStartMs = Date.now()
+
 /**
  * Normalize a raw MCP wire tool name to the tracker's expected form. The proxy sees `execute` /
  * `batch_execute` on the wire; ExecuteClaimTracker only matches `mcp__gemus__execute` /
@@ -71,9 +75,12 @@ export function injectSteering(msg) {
  * @param {string} deps.server   平台 origin（不含 /api/mcp）
  * @param {string} deps.apiKey   用户 mak_ key
  * @param {string} deps.codexHome  ~/.codex（idle-timer fallback 用 findRolloutFile(session_id) 定位 rollout）
+ * @param {import('@gemus/codex-backfill-core').GemusToolCall} [deps.call] footprint-0 交付 transport
+ *   （#1756 Layer 1a）：省略 → connect-per-call（每图新开 key-only session）；传入 → 在 proxy 已有
+ *   upstream 连接上注入 execute/canvas_edit（不占新槽，即便 cap 被泄漏填满仍能交付）。
  * @param {(msg: string, obj?: unknown) => void} [deps.log]
  */
-export function createBackfiller({ server, apiKey, codexHome, log = () => {} }) {
+export function createBackfiller({ server, apiKey, codexHome, call, log = () => {} }) {
   /** @type {Map<string, { tracker: InstanceType<typeof core.ExecuteClaimTracker>, workflowId?: string, sessionId?: string }>} */
   const turns = new Map() // keyed by turn_id; bounded (evict oldest) so a long session can't leak
   const TURN_CAP = 64
@@ -123,7 +130,7 @@ export function createBackfiller({ server, apiKey, codexHome, log = () => {} })
 
   /** orphan 一张图（Mode B 需真实 workflowId），**只在成功后**标记 seen；返回是否成功。 */
   async function orphanOne(workflowId, image) {
-    const r = await core.addImageToCanvas({ server, apiKey, workflowId, image })
+    const r = await core.addImageToCanvas({ server, apiKey, workflowId, image, call })
     if (r.ok) {
       seen.add(image.callId)
       return true
@@ -143,14 +150,27 @@ export function createBackfiller({ server, apiKey, codexHome, log = () => {} })
   async function backfillTurnInner({ turnKey, sessionId, rolloutPath, salvageOnly }) {
     const t = turns.get(turnKey)
     const sid = sessionId || t?.sessionId
-    const path = rolloutPath || core.findRolloutFile(codexHome, sid)
-    const jsonl = core.readRollout(path)
-    const all = core.extractImageOutputs(jsonl)
+    // #1756 Layer 2: 优先读 generated_images 落盘文件（去 rollout-scrape 脆化）。三态 fallback——
+    // 仅目录整体不可用（旧 codex 不落盘）才回退 rollout；目录可用即锁定文件源（即便过滤后空），
+    // 否则会绕过 mtime 守卫把历史图从 rollout 重新捞出重复交付。
+    const fileResult = sid
+      ? core.readGeneratedImageFiles(codexHome, sid, procStartMs)
+      : { available: false, images: [] }
+    let all
+    let source
+    if (fileResult.available) {
+      all = fileResult.images
+      source = 'generated_images'
+    } else {
+      const path = rolloutPath || core.findRolloutFile(codexHome, sid)
+      all = core.extractImageOutputs(core.readRollout(path))
+      source = path || '(none)'
+    }
     const fresh = all.filter((img) => !seen.has(img.callId))
 
     if (fresh.length === 0) {
       // 图还没 flush（idle 过早触发）或都已交付 —— 都不动 seen/turn 状态，留给后续 hook。
-      log('backfill: no fresh images', { turnKey, salvageOnly, path: path || '(none)' })
+      log('backfill: no fresh images', { turnKey, salvageOnly, source })
       return { delivered: 0, orphaned: 0, dropped: 0 }
     }
 
@@ -175,12 +195,17 @@ export function createBackfiller({ server, apiKey, codexHome, log = () => {} })
     let delivered = 0
     let orphaned = 0
     for (const { nodeId, image } of claims) {
-      const r = await core.deliverImageToNode({ server, apiKey, workflowId, nodeId, image })
+      const r = await core.deliverImageToNode({ server, apiKey, workflowId, nodeId, image, call })
       if (r.ok) {
         seen.add(image.callId)
         delivered++
+      } else if (r.timedOut) {
+        // #1756: 注入交付超时 = 结果未知（平台 job 可能仍在跑并最终写 DB）。**不 orphan、不标 seen**——
+        // 否则同图既落节点又多一个 image-upload 孤儿。留 fresh，交给下轮 pass（Stop hook/idle）在 job
+        // 落地后经 execute 幂等门重判（already_completed 才安全 orphan）。
+        log('backfill: deliver timed out — leaving image fresh (no orphan)', { nodeId, callId: image.callId })
       } else if (await orphanOne(workflowId, image)) {
-        // already_completed / 其它失败 → orphan 保底（镜像 bridge：新图未落节点则至少 image-upload）。
+        // already_completed / 其它确定性失败 → orphan 保底（镜像 bridge：新图未落节点则至少 image-upload）。
         orphaned++
       } else {
         log('backfill: deliver+orphan both failed', { nodeId, callId: image.callId, error: r.error ?? r.code })

package/src/proxy.mjs

@@ -24,6 +24,7 @@ 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'
 
 const KEY = process.env.GEMUS_KEY || ''
 const GEMUS_URL = process.env.GEMUS_URL || 'https://gemus.ai/api/mcp'
@@ -33,16 +34,68 @@ const CODEX_HOME = process.env.CODEX_HOME || path.join(os.homedir(), '.codex')
 // 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
 const LOG = process.env.PROXY_LOG // optional debug log path
 const log = (dir, m) => {
   if (!LOG) return
   fs.appendFileSync(LOG, `[${new Date().toISOString()}] ${dir} ${typeof m === 'string' ? m : JSON.stringify(m).slice(0, 1000)}\n`)
 }
 
+// ── 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 } } : {}) },
+  }
+  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),
 })
 
@@ -196,18 +249,49 @@ const upstream = new StreamableHTTPClientTransport(new URL(GEMUS_URL), {
 const stdio = new StdioServerTransport()
 
 stdio.onmessage = (m) => { tapClientToServer(m); log('C->G', m); upstream.send(m).catch((e) => log('ERR-http-send', String(e))) }
-upstream.onmessage = (m) => { tapServerToClient(m); steerOnInit(m); log('G->C', m); stdio.send(m).catch((e) => log('ERR-stdio-send', String(e))) }
+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))
+    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
+  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
+}
+
 let shuttingDown = false
 async function shutdown() {
   if (shuttingDown) return
   shuttingDown = true
+  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()
   try { hookServer.close() } catch { /* ignore */ }
   if (discoveryFile) { try { fs.unlinkSync(discoveryFile) } catch { /* ignore */ } }
   try { await upstream.terminateSession() } catch { /* ignore */ }
@@ -223,4 +307,5 @@ process.on('SIGINT', shutdown)
 
 await upstream.start()
 await stdio.start()
-log('STARTED', { GEMUS_URL, SERVER_ORIGIN, hasKey: Boolean(KEY), pid: process.pid, idleMs: IDLE_MS })
+startHeartbeat()
+log('STARTED', { GEMUS_URL, SERVER_ORIGIN, hasKey: Boolean(KEY), pid: process.pid, idleMs: IDLE_MS, heartbeatMs: HEARTBEAT_MS })