@gemus/mcp-proxy 0.1.4 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemus/mcp-proxy",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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.2"
+    "@gemus/codex-backfill-core": "0.1.3"
   },
   "engines": {
     "node": ">=18"

package/src/__tests__/backfill.test.ts

@@ -74,7 +74,7 @@ beforeEach(() => {
   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: [] })
+  mocks.readGeneratedImageFiles.mockReset().mockReturnValue({ available: false, images: [], failedCallIds: [] })
 })
 
 describe('normalizeToolName (tap → tracker)', () => {
@@ -353,4 +353,42 @@ describe('backfillTurn — Layer 2 file byte source (#1756)', () => {
     expect(mocks.readRollout).toHaveBeenCalledWith('/x')
     expect(r.delivered).toBe(1)
   })
+
+  it('exec-* file-source image (opaque call-id) is delivered exactly once (#1968)', async () => {
+    const bf = makeBackfiller()
+    observeExecuteAnchor(bf, 1, 't1', 's1', 'wf_real', 'nodeA')
+    mocks.readGeneratedImageFiles.mockReturnValue({
+      available: true,
+      images: [{ callId: 'exec-3eb2a29c', base64: 'iVBORw0KGgoAAAA1', mimeType: 'image/png' }],
+      failedCallIds: [],
+    })
+
+    const r = await bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: '/x', salvageOnly: false })
+
+    expect(mocks.readRollout).not.toHaveBeenCalled()
+    expect(r.delivered).toBe(1)
+    expect(mocks.deliverImageToNode).toHaveBeenCalledTimes(1)
+    expect(mocks.deliverImageToNode.mock.calls[0][0]).toMatchObject({
+      nodeId: 'nodeA',
+      image: { callId: 'exec-3eb2a29c' },
+    })
+  })
+
+  it('unreadable fresh candidate is recovered from rollout by EXACT call-id only — no history bypass (#1968)', async () => {
+    const bf = makeBackfiller()
+    observeExecuteAnchor(bf, 1, 't1', 's1', 'wf_real', 'nodeA')
+    // File source: nothing readable, but one fresh candidate failed to read (torn write).
+    mocks.readGeneratedImageFiles.mockReturnValue({ available: true, images: [], failedCallIds: ['exec-torn'] })
+    // Rollout holds the failed id AND an unrelated historical image that must NOT be surfaced.
+    mocks.readRollout.mockReturnValue(rollout([['exec-torn', 'iVBORw0KGgoAAAA9'], ['ig_history', 'iVBORw0KGgoAAAA8']]))
+
+    const r = await bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: '/x', salvageOnly: false })
+
+    expect(mocks.readRollout).toHaveBeenCalledWith('/x')
+    expect(r.delivered).toBe(1)
+    expect(mocks.deliverImageToNode).toHaveBeenCalledTimes(1)
+    expect(mocks.deliverImageToNode.mock.calls[0][0]).toMatchObject({ image: { callId: 'exec-torn' } })
+    // The historical image was in the rollout but is NOT in failedCallIds → never delivered or orphaned.
+    expect(mocks.addImageToCanvas).not.toHaveBeenCalled()
+  })
 })

package/src/__tests__/mcpHeaders.test.ts

@@ -1,11 +1,32 @@
 import { describe, expect, it } from 'vitest'
+import { CLIENT_CAPABILITIES } from '@gemus/codex-backfill-core'
 import { buildProxyUpstreamHeaders } from '../mcpHeaders.mjs'
 
 describe('buildProxyUpstreamHeaders', () => {
-  it('advertises the canonical Codex MCP capabilities alongside bearer authentication', () => {
+  it('advertises only the capabilities the proxy can actually fulfil', () => {
     expect(buildProxyUpstreamHeaders('mak_test123')).toEqual({
       Authorization: 'Bearer mak_test123',
       'X-Gemus-Client-Capabilities': 'agent-authored-prompts,codex-imagen',
     })
   })
+
+  it('never advertises codex-instant-delivery — the proxy has no ImageScheduler to renew the lease (#2049)', () => {
+    // 该能力门控服务端的 AWAITING_CLIENT execute 分支，要求客户端有 scheduler 每 60s renewLease。
+    // 只有 bridge 有（且 probe 门控，见 bridge/src/cli.ts）。proxy 没有 —— 发了它就等于承诺一个
+    // 永不到来的续租 → 5min 后 CLIENT_LEASE_EXPIRED → 图 orphan 成孤立 image-upload 节点。
+    // absent → 服务端回退经典两阶段 client-delivered 协议，proxy 完全支持（backfill.mjs）。
+    const header = buildProxyUpstreamHeaders('mak_test123')['X-Gemus-Client-Capabilities']
+    expect(header).not.toContain('codex-instant-delivery')
+  })
+
+  it('stays a strict subset of the shared allowlist — a new capability must not auto-inherit (#2049)', () => {
+    // 回归门：本 bug 的成因正是 proxy 发「整个 CLIENT_CAPABILITIES 数组」—— #1969 往数组里加了
+    // codex-instant-delivery，proxy 就自动继承了一个它做不到的承诺，而 #1990 把红掉的断言改成
+    // 迎合它。此断言让「加能力」与「proxy 声称支持它」变成两个独立决策，不再自动传染。
+    const advertised = buildProxyUpstreamHeaders('mak_test123')['X-Gemus-Client-Capabilities'].split(',')
+    for (const capability of advertised) {
+      expect(CLIENT_CAPABILITIES).toContain(capability)
+    }
+    expect(advertised.length).toBeLessThan(CLIENT_CAPABILITIES.length)
+  })
 })

package/src/backfill.mjs

@@ -137,17 +137,33 @@ export function createBackfiller({ server, apiKey, codexHome, call, log = () =>
   async function backfillTurnInner({ turnKey, sessionId, rolloutPath, salvageOnly }) {
     const t = turns.get(turnKey)
     const sid = sessionId || t?.sessionId
-    // #1756 Layer 2: 优先读 generated_images 落盘文件（去 rollout-scrape 脆化）。三态 fallback——
-    // 仅目录整体不可用（旧 codex 不落盘）才回退 rollout；目录可用即锁定文件源（即便过滤后空），
-    // 否则会绕过 mtime 守卫把历史图从 rollout 重新捞出重复交付。
+    // #1756 Layer 2: 优先读 generated_images 落盘文件（去 rollout-scrape 脆化）。仅目录整体不可用
+    // （旧 codex 不落盘）才整源回退 rollout；目录可用即锁定文件源，否则会绕过 mtime 守卫把历史图从
+    // rollout 重新捞出重复交付。#1968：文件源里「已确认 fresh 但读失败」的候选（torn/locked write）
+    // 按精确 call-id 定向从 rollout 恢复——只捞这几个 id，不换整源、不越 mtime 守卫。
     const fileResult = sid
       ? core.readGeneratedImageFiles(codexHome, sid, procStartMs)
-      : { available: false, images: [] }
+      : { available: false, images: [], failedCallIds: [] }
     let all
     let source
     if (fileResult.available) {
       all = fileResult.images
       source = 'generated_images'
+      const failedCallIds = fileResult.failedCallIds || []
+      if (failedCallIds.length) {
+        const path = rolloutPath || core.findRolloutFile(codexHome, sid)
+        const want = new Set(failedCallIds)
+        const recovered = core.extractImageOutputs(core.readRollout(path)).filter((img) => want.has(img.callId))
+        if (recovered.length) {
+          all = all.concat(recovered)
+          source = `${source}+rollout`
+        }
+        log('backfill: unreadable generated_images candidates', {
+          turnKey,
+          failed: failedCallIds.length,
+          recovered: recovered.length,
+        })
+      }
     } else {
       const path = rolloutPath || core.findRolloutFile(codexHome, sid)
       all = core.extractImageOutputs(core.readRollout(path))

package/src/mcpHeaders.mjs

@@ -4,9 +4,36 @@ import {
   serializeClientCapabilities,
 } from '@gemus/codex-backfill-core'
 
+/**
+ * #2049：proxy 只 advertise **它自己能履行**的能力 —— 不是 `CLIENT_CAPABILITIES` 全集。
+ *
+ * `CLIENT_CAPABILITIES` 是**所有已知能力的 allowlist**（共享 SSOT），不是「每个客户端都支持」的清单。
+ * 各客户端各自声明自己能兑现的子集：bridge 见 `bridge/src/cli.ts`（`imageScheduler` 与
+ * `activeCapabilities` **成对注入** —— 有 scheduler 才发 capability，且 probe 门控）。
+ *
+ * **`codex-instant-delivery` 必须排除**：它门控服务端的 AWAITING_CLIENT execute 分支，
+ * 要求客户端有 ImageScheduler 每 60s `renewLease`。**proxy 没有 scheduler**（本包与
+ * `@gemus/codex-backfill-core` 里 `renew`/`lease` 零命中）。发了它 = 承诺一个永不到来的续租：
+ *   execute 建 AWAITING_CLIENT job（lease=+5min）→ 无人续 → `CLIENT_LEASE_EXPIRED` → 节点 FAILED
+ *   → Codex 的图回来时目标已死 → `backfill.mjs` orphan 兜底 → 孤立 `image-upload` 节点。
+ * 真机实测见 #2049。
+ * **不发它 → 服务端回退经典两阶段 client-delivered 协议，proxy 完全支持**（`backfill.mjs`
+ * tap execute + 注入交付）—— 这正是 `codex-backfill-core/src/mcp.ts` 那条注释写的
+ * "absent → the classic dryRun/Phase-2 two-phase client-delivered protocol is used unchanged"。
+ *
+ * ⚠️ **往 `CLIENT_CAPABILITIES` 加新能力时**：默认**不会**、也**不该**自动出现在这里。先问
+ * 「proxy 拿什么兑现它？」—— 本 bug 的成因正是「发全集」让新能力自动传染（#1969 加，proxy 白捡，
+ * #1990 把红掉的断言改成迎合）。`__tests__/mcpHeaders.test.ts` 有严格子集断言守着这条。
+ */
+const PROXY_UNSUPPORTED_CAPABILITIES = new Set(['codex-instant-delivery'])
+
+const PROXY_CAPABILITIES = Object.freeze(
+  CLIENT_CAPABILITIES.filter((capability) => !PROXY_UNSUPPORTED_CAPABILITIES.has(capability)),
+)
+
 export function buildProxyUpstreamHeaders(apiKey) {
   return {
     Authorization: `Bearer ${apiKey}`,
-    [CLIENT_CAPABILITIES_HEADER]: serializeClientCapabilities(CLIENT_CAPABILITIES),
+    [CLIENT_CAPABILITIES_HEADER]: serializeClientCapabilities(PROXY_CAPABILITIES),
   }
 }