@gemus/mcp-proxy 0.1.5 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemus/mcp-proxy",
-  "version": "0.1.5",
+  "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": {

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/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),
   }
 }