@gemus/mcp-proxy 0.1.2 → 0.1.5

package/README.md

@@ -1,4 +1,4 @@
-# @gemus/mcp-proxy (Issue #1751, P1 — WIP)
+# @gemus/mcp-proxy (Issues #1751, #1756, #1917)
 
 Local stdio↔HTTP MCP proxy that gives **Codex desktop (direct-connect / Mode B)** users canvas
 image write-back. Bundled into the Codex plugin (`.codex-plugin/`), declared as a **command-based**
@@ -6,11 +6,13 @@ MCP server so codex spawns it locally; the proxy owns upstream auth to the remot
 (Codex does no OAuth for stdio servers). Full design: `docs/plans/1751-codex-desktop-companion.md`
 and `docs/architecture/agent architecture/codex-desktop-companion.md`.
 
-## Status: minimal skeleton, behavioral checkpoint PASSED
+## Status: implemented
 
-`src/proxy.mjs` is the validated passthrough+tap skeleton. The backfill delivery layer (Stop-hook
-endpoint → read rollout via `transcript_path` → `ExecuteClaimTracker` → key-only `deliverImageToNode`)
-is the next build increment (plan Steps 2–4).
+`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.
 
 ## What was validated end-to-end (2026-07-06, codex-cli 0.142.2 → local dev `/api/mcp`)
 
@@ -23,7 +25,8 @@ is the next build increment (plan Steps 2–4).
   `workflowId` from `arguments`, and **turn/thread identity from `_meta.x-codex-turn-metadata`
   (`thread_id`/`turn_id`)** — so per-turn scoping needs no Stop hook. `execute` is the same path.
 - **(c) turn-end + retrieval** — `Stop` hook fires post-flush carrying `transcript_path` → exact
-  rollout; imagegen writes `generated_images/<session>/ig_<call_id>.png` + rollout `saved_path`+base64.
+  rollout; imagegen writes `generated_images/<session>/<sanitized-call-id>.png` (historically `ig_*`,
+  currently `call_*`) + rollout `saved_path`+base64.
 - **Session cap** — `KEY_ONLY_SESSION_CAP=3`/user is real; the proxy MUST `DELETE` its upstream
   session on close (implemented in `shutdown()`) to avoid leaking slots.
 
@@ -53,4 +56,4 @@ GEMUS_KEY=mak_... GEMUS_URL=http://localhost:3000/api/mcp PROXY_LOG=/tmp/proxy.l
 ```
 
 Env: `GEMUS_KEY` (required), `GEMUS_URL` (default `https://gemus.ai/api/mcp`), `PROXY_LOG` (optional
-debug log), `PROXY_BACKFILL_IDLE_MS` (default 30000 — turn-idle fallback before salvage-orphan).
+debug log), `PROXY_BACKFILL_IDLE_MS` (default 180000 — turn-idle fallback before salvage-orphan).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemus/mcp-proxy",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "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.1"
+    "@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)', () => {
@@ -92,14 +92,25 @@ describe('normalizeToolName (tap → tracker)', () => {
 })
 
 describe('injectSteering (Mode-B initialize instructions)', () => {
-  it('appends companion steering to the initialize response instructions', () => {
+  it('appends a search-neutral skill bootstrap to initialize instructions', () => {
     const msg = { jsonrpc: '2.0', id: 1, result: { protocolVersion: '2024-11-05', serverInfo: { name: 'gemus' } } }
     expect(injectSteering(msg)).toBe(true)
-    expect(msg.result.instructions).toContain('auto-backfilled')
-    expect(msg.result.instructions).toContain('NEVER') // don't self-forward
+    expect(msg.result.instructions).toContain('gemus-getting-started')
+    expect(msg.result.instructions).toContain('gemus-codex-imagen')
     expect(msg.result.instructions).toBe(COMPANION_STEERING)
   })
 
+  it('does not pollute deferred search documents with registered tool names', () => {
+    const toolNames = [
+      'canvas_read', 'view_image', 'node_list', 'workflow_list', 'canvas_edit', 'ppt_edit',
+      'open_canvas', 'blueprint', 'execute', 'batch_execute', 'recall_history',
+    ]
+    for (const toolName of toolNames) {
+      const exactName = new RegExp(`(?<![A-Za-z0-9_])${toolName}(?![A-Za-z0-9_])`, 'i')
+      expect(COMPANION_STEERING, `companion steering references ${toolName}`).not.toMatch(exactName)
+    }
+  })
+
   it('preserves any existing server instructions (appends, not replaces)', () => {
     const msg = { id: 1, result: { protocolVersion: '1', instructions: 'server says hi' } }
     injectSteering(msg)
@@ -304,7 +315,7 @@ describe('backfillTurn — Layer 2 file byte source (#1756)', () => {
     // 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' }],
+      images: [{ callId: 'call_current', base64: 'iVBORw0KGgoAAAA1', mimeType: 'image/png' }],
     })
 
     const r = await bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: '/x', salvageOnly: false })
@@ -312,7 +323,10 @@ describe('backfillTurn — Layer 2 file byte source (#1756)', () => {
     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' } })
+    expect(mocks.deliverImageToNode.mock.calls[0][0]).toMatchObject({
+      nodeId: 'nodeA',
+      image: { callId: 'call_current' },
+    })
   })
 
   it('available but empty → no delivery, and does NOT fall back to rollout (mtime guard preserved)', async () => {
@@ -339,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

@@ -0,0 +1,11 @@
+import { describe, expect, it } from 'vitest'
+import { buildProxyUpstreamHeaders } from '../mcpHeaders.mjs'
+
+describe('buildProxyUpstreamHeaders', () => {
+  it('advertises the canonical Codex MCP capabilities alongside bearer authentication', () => {
+    expect(buildProxyUpstreamHeaders('mak_test123')).toEqual({
+      Authorization: 'Bearer mak_test123',
+      'X-Gemus-Client-Capabilities': 'agent-authored-prompts,codex-imagen',
+    })
+  })
+})

package/src/backfill.mjs

@@ -34,27 +34,14 @@ export function normalizeToolName(name) {
   return WIRE_TO_NORMALIZED[name] ?? name
 }
 
-// Companion steering (Mode B has no bridge to inject CLIENT_DELIVERED_GUIDANCE into the system prompt).
-// This proxy IS the backfiller, so it tells codex — via the MCP initialize `instructions` field — not to
-// self-forward imagegen output. Mirrors src/lib/agent/core/prompt/workflowBehavior.ts (condensed). Without
-// it codex hunts the file / uploads it to a public host to self-deliver (#1751 real-machine observation).
+// Keep initialize instructions search-neutral. Codex appends this namespace text to every deferred
+// tool's BM25 document, so operational rules and exact tool names live in installed plugin skills.
 export const COMPANION_STEERING = [
-  '# Gemus companion — codex-imagen is auto-backfilled',
+  '# Gemus companion',
   '',
-  'A local Gemus companion backfills your own image generations onto the planned canvas nodes at turn',
-  'end. For a `codex-imagen` (gen-image) node: (1) create the node with config.model="codex-imagen",',
-  '(2) call `execute` with dryRun:true and read the returned resolvedPrompt, (3) generate the image',
-  'LOCALLY with your built-in imagegen, then (4) STOP.',
-  '',
-  'NEVER locate, read, host, upload, or submit the imagegen file yourself — you cannot access it and it',
-  'is delivered for you. NEVER pass `content` for a codex-imagen node, and NEVER spin up a local HTTP',
-  'server or upload the image to a public host to "deliver" it. A codex-imagen node showing no output /',
-  'clientDeliveredStatus:"awaiting_backfill" DURING your turn is ON TRACK, not a failure — do not re-read',
-  'it in a loop, do not switch its model to a platform provider (gemini/etc), do not self-forward. Just',
-  'end your turn; the image arrives on the node after it.',
-  '',
-  '(Text is the exception: codex-text has no backfill — self-forward with execute dryRun:false +',
-  'content:{text:"..."}.)',
+  'Before using Gemus, load and follow the installed `gemus-getting-started` skill.',
+  'For local image generation and turn-end backfill, also load `gemus-codex-imagen`.',
+  'These skills are the authoritative operational guidance for this direct MCP connection.',
 ].join('\n')
 
 /**
@@ -150,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

@@ -0,0 +1,12 @@
+import {
+  CLIENT_CAPABILITIES,
+  CLIENT_CAPABILITIES_HEADER,
+  serializeClientCapabilities,
+} from '@gemus/codex-backfill-core'
+
+export function buildProxyUpstreamHeaders(apiKey) {
+  return {
+    Authorization: `Bearer ${apiKey}`,
+    [CLIENT_CAPABILITIES_HEADER]: serializeClientCapabilities(CLIENT_CAPABILITIES),
+  }
+}

package/src/proxy.mjs

@@ -25,6 +25,7 @@ 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'
 
 const KEY = process.env.GEMUS_KEY || ''
 const GEMUS_URL = process.env.GEMUS_URL || 'https://gemus.ai/api/mcp'
@@ -244,7 +245,7 @@ if (typeof hookServer.unref === 'function') hookServer.unref()
 
 // ── transparent JSON-RPC passthrough (raw send/onmessage) ──────────────────────────────────────
 const upstream = new StreamableHTTPClientTransport(new URL(GEMUS_URL), {
-  requestInit: { headers: { Authorization: `Bearer ${KEY}` } },
+  requestInit: { headers: buildProxyUpstreamHeaders(KEY) },
 })
 const stdio = new StdioServerTransport()