@gemus/mcp-proxy 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# @gemus/mcp-proxy (Issue #1751, P1 — WIP)
+
+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**
+MCP server so codex spawns it locally; the proxy owns upstream auth to the remote gemus `/api/mcp`
+(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
+
+`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).
+
+## What was validated end-to-end (2026-07-06, codex-cli 0.142.2 → local dev `/api/mcp`)
+
+- **Transparent passthrough** — initialize + tools/list relay all **12 gemus tools** (incl.
+  `execute`/`batch_execute`). SDK transport auto-captures `mcp-session-id` from the initialize
+  response; raw send/onmessage wiring works with normal sequencing.
+- **(e) proxy-per-session** — `codex mcp add gemus -- node <proxy>` → codex spawns one proxy per
+  session (`clientInfo: codex-mcp-client 0.142.2`); reports `Auth: Unsupported` (proxy owns auth).
+- **(d) execute-tap** — real codex `tools/call` (`workflow_list`, `canvas_read{workflowId}`) tapped;
+  `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.
+- **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.
+
+## Install (Codex desktop)
+
+The key is supplied as a **literal** in the user's *local* codex config — codex does NOT interpolate
+`${VAR}` in an MCP server's `env`, and a public plugin manifest must never carry a key (Step-0.4
+findings). So the keyed MCP server is registered locally, not via the plugin manifest:
+
+```bash
+# 1. Register the proxy as codex's gemus MCP server (writes a literal key into ~/.codex/config.toml).
+codex mcp add gemus --env GEMUS_KEY=mak_<your key> -- npx -y @gemus/mcp-proxy
+#    (get a mak_ key from gemus.ai → Settings → MCP Keys; GEMUS_URL defaults to https://gemus.ai/api/mcp)
+
+# 2. Install the plugin (Stop hook + skills) from the gemus marketplace, then TRUST the hook:
+codex plugin add gemus@<marketplace>
+#    In interactive codex run `/hooks` and trust the gemus Stop hook — REQUIRED for canvas backfill.
+#    Without a trusted hook, images still land on the canvas (orphan node), just not the planned node.
+```
+
+## Local dev
+
+```bash
+pnpm --filter @gemus/codex-backfill-core build          # proxy imports the built core at runtime
+GEMUS_KEY=mak_... GEMUS_URL=http://localhost:3000/api/mcp PROXY_LOG=/tmp/proxy.log node src/proxy.mjs
+# or register against dev:  codex mcp add gemus --env GEMUS_KEY=mak_... GEMUS_URL=http://localhost:3000/api/mcp -- node <abs>/src/proxy.mjs
+```
+
+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).

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@gemus/mcp-proxy",
+  "version": "0.1.0",
+  "description": "Local stdio<->HTTP MCP proxy for Codex desktop: transparent passthrough + execute tap + imagegen backfill (Issue #1751, P1).",
+  "type": "module",
+  "bin": {
+    "gemus-mcp-proxy": "src/proxy.mjs"
+  },
+  "main": "src/proxy.mjs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Gemus-AI/Gemus.git",
+    "directory": "packages/gemus-mcp-proxy"
+  },
+  "homepage": "https://gemus.ai",
+  "keywords": [
+    "gemus",
+    "mcp",
+    "codex",
+    "proxy",
+    "image-generation"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@gemus/codex-backfill-core": "0.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "license": "MIT",
+  "private": false,
+  "scripts": {
+    "start": "node src/proxy.mjs"
+  }
+}

package/src/__tests__/backfill.test.ts

@@ -0,0 +1,225 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+
+/**
+ * @gemus/mcp-proxy backfill orchestration (#1751, Mode B). Mocks only the core's NETWORK + rollout-IO
+ * (deliverImageToNode / addImageToCanvas / readRollout / findRolloutFile); keeps extractImageOutputs +
+ * ExecuteClaimTracker + unwrapMcpContent REAL so the tap→tracker→claim/salvage wiring is exercised
+ * end-to-end. Shares the same @modelcontextprotocol/sdk instance as bridge tests via the vitest alias.
+ */
+const mocks = vi.hoisted(() => ({
+  deliverImageToNode: vi.fn(),
+  addImageToCanvas: vi.fn(),
+  readRollout: vi.fn(),
+  findRolloutFile: vi.fn(),
+}))
+
+vi.mock('@gemus/codex-backfill-core', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@gemus/codex-backfill-core')>()
+  return {
+    ...actual, // real extractImageOutputs / ExecuteClaimTracker / EXECUTE_TOOL_NAMES / unwrapMcpContent
+    deliverImageToNode: mocks.deliverImageToNode,
+    addImageToCanvas: mocks.addImageToCanvas,
+    readRollout: mocks.readRollout,
+    findRolloutFile: mocks.findRolloutFile,
+  }
+})
+
+import { createBackfiller, normalizeToolName, injectSteering, COMPANION_STEERING } from '../backfill.mjs'
+import { EXECUTE_TOOL_NAMES } from '@gemus/codex-backfill-core'
+
+/** rollout JSONL with N imagegen images (distinct call_ids, PNG-magic base64 so mime→png). */
+function rollout(images: Array<[string, string]>): string {
+  return images
+    .map(([callId, b64]) =>
+      JSON.stringify({ payload: { type: 'image_generation_end', call_id: callId, result: b64 } }),
+    )
+    .join('\n')
+}
+
+/** MCP ContentBlock[] wrap of a structured tool result (what the wire carries; unwrapMcpContent restores it). */
+function wrap(obj: unknown) {
+  return [{ type: 'text', text: JSON.stringify(obj) }]
+}
+
+const IMG_A: [string, string] = ['ig_a', 'iVBORw0KGgoAAAA1']
+const IMG_B: [string, string] = ['ig_b', 'iVBORw0KGgoAAAA2']
+
+/** Simulate one `execute` Phase-1 awaiting_client_content anchor for `nodeId` on a turn. */
+function observeExecuteAnchor(
+  bf: ReturnType<typeof createBackfiller>,
+  jsonrpcId: number,
+  turnKey: string,
+  sessionId: string,
+  workflowId: string,
+  nodeId: string,
+) {
+  bf.observeCall({ jsonrpcId, turnKey, sessionId, name: 'execute', args: { workflowId, nodeId, dryRun: true } })
+  bf.observeResult({
+    jsonrpcId,
+    turnKey,
+    name: 'execute',
+    resultContent: wrap({ status: 'awaiting_client_content', nodeId }),
+  })
+}
+
+function makeBackfiller() {
+  return createBackfiller({ server: 'http://localhost:3000', apiKey: 'mak_test', codexHome: '/fake/.codex' })
+}
+
+beforeEach(() => {
+  mocks.deliverImageToNode.mockReset().mockResolvedValue({ ok: true, status: 'processing' })
+  mocks.addImageToCanvas.mockReset().mockResolvedValue({ ok: true, entityId: 'agent_x' })
+  mocks.readRollout.mockReset().mockReturnValue('')
+  mocks.findRolloutFile.mockReset().mockReturnValue('/fake/rollout.jsonl')
+})
+
+describe('normalizeToolName (tap → tracker)', () => {
+  it('maps wire execute names to the tracker constants', () => {
+    expect(normalizeToolName('execute')).toBe('mcp__gemus__execute')
+    expect(normalizeToolName('batch_execute')).toBe('mcp__gemus__batch_execute')
+    // the whole point: the normalized name must be one the tracker actually matches.
+    expect(EXECUTE_TOOL_NAMES.has(normalizeToolName('execute'))).toBe(true)
+    expect(EXECUTE_TOOL_NAMES.has(normalizeToolName('batch_execute'))).toBe(true)
+  })
+  it('passes non-execute tool names through unchanged', () => {
+    expect(normalizeToolName('canvas_read')).toBe('canvas_read')
+    expect(normalizeToolName('workflow_list')).toBe('workflow_list')
+  })
+})
+
+describe('injectSteering (Mode-B initialize instructions)', () => {
+  it('appends companion steering to the initialize response 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).toBe(COMPANION_STEERING)
+  })
+
+  it('preserves any existing server instructions (appends, not replaces)', () => {
+    const msg = { id: 1, result: { protocolVersion: '1', instructions: 'server says hi' } }
+    injectSteering(msg)
+    expect(msg.result.instructions).toContain('server says hi')
+    expect(msg.result.instructions).toContain('Gemus companion')
+  })
+
+  it('is a no-op for non-initialize messages (tool results, notifications)', () => {
+    const toolResult = { id: 5, result: { content: [{ type: 'text', text: '{}' }] } }
+    expect(injectSteering(toolResult)).toBe(false)
+    expect(toolResult.result.instructions).toBeUndefined()
+    expect(injectSteering({ method: 'notifications/message' })).toBe(false)
+  })
+})
+
+describe('backfillTurn — claim path (Stop hook)', () => {
+  it('delivers each scavenged image to its planned node (key-only: real workflowId, no sessionId header)', async () => {
+    const bf = makeBackfiller()
+    observeExecuteAnchor(bf, 1, 't1', 's1', 'wf_real', 'nodeA')
+    observeExecuteAnchor(bf, 2, 't1', 's1', 'wf_real', 'nodeB')
+    mocks.readRollout.mockReturnValue(rollout([IMG_A, IMG_B]))
+
+    const r = await bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: '/precise.jsonl', salvageOnly: false })
+
+    expect(r).toEqual({ delivered: 2, orphaned: 0, dropped: 0 })
+    // Stop hook path reads the PRECISE rollout (transcript_path), not findRolloutFile.
+    expect(mocks.readRollout).toHaveBeenCalledWith('/precise.jsonl')
+    expect(mocks.findRolloutFile).not.toHaveBeenCalled()
+    // N:N ordered claim: nodeA→first image, nodeB→second.
+    expect(mocks.deliverImageToNode).toHaveBeenCalledTimes(2)
+    const calls = mocks.deliverImageToNode.mock.calls.map((c) => c[0])
+    expect(calls[0]).toMatchObject({ workflowId: 'wf_real', nodeId: 'nodeA', image: { callId: 'ig_a' } })
+    expect(calls[1]).toMatchObject({ workflowId: 'wf_real', nodeId: 'nodeB', image: { callId: 'ig_b' } })
+    // key-only invariant: no X-Gemus-Session-Id (no sessionId passed to the delivery fn).
+    expect(calls[0].sessionId).toBeUndefined()
+    expect(mocks.addImageToCanvas).not.toHaveBeenCalled()
+  })
+
+  it('falls back to orphan when deliver fails (e.g. already_completed) — image not lost', async () => {
+    const bf = makeBackfiller()
+    observeExecuteAnchor(bf, 1, 't1', 's1', 'wf_real', 'nodeA')
+    mocks.readRollout.mockReturnValue(rollout([IMG_A]))
+    mocks.deliverImageToNode.mockResolvedValue({ ok: false, code: 'ALREADY_COMPLETED' })
+
+    const r = await bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: '/x', salvageOnly: false })
+
+    expect(mocks.deliverImageToNode).toHaveBeenCalledTimes(1)
+    expect(mocks.addImageToCanvas).toHaveBeenCalledTimes(1) // orphan fallback
+    expect(r).toEqual({ delivered: 0, orphaned: 1, dropped: 0 })
+  })
+})
+
+describe('backfillTurn — salvageOnly fallback (untrusted hook / idle timer)', () => {
+  it('orphans every fresh image and NEVER calls claim/deliver, even with pending anchors', async () => {
+    const bf = makeBackfiller()
+    // A legit multi-image turn with pending anchors — salvage must NOT mis-claim them.
+    observeExecuteAnchor(bf, 1, 't1', 's1', 'wf_real', 'nodeA')
+    observeExecuteAnchor(bf, 2, 't1', 's1', 'wf_real', 'nodeB')
+    mocks.readRollout.mockReturnValue(rollout([IMG_A, IMG_B]))
+
+    const r = await bf.backfillTurn({ turnKey: 't1', rolloutPath: null, salvageOnly: true })
+
+    // idle fallback has no transcript_path → locates rollout via findRolloutFile(session_id).
+    expect(mocks.findRolloutFile).toHaveBeenCalledWith('/fake/.codex', 's1')
+    expect(mocks.deliverImageToNode).not.toHaveBeenCalled() // never claim in salvage
+    expect(mocks.addImageToCanvas).toHaveBeenCalledTimes(2)
+    expect(r).toEqual({ delivered: 0, orphaned: 2, dropped: 0 })
+  })
+})
+
+describe('backfillTurn — idempotency + guards', () => {
+  it('is idempotent across the two triggers via the seen-set (2nd pass no-ops)', async () => {
+    const bf = makeBackfiller()
+    observeExecuteAnchor(bf, 1, 't1', 's1', 'wf_real', 'nodeA')
+    mocks.readRollout.mockReturnValue(rollout([IMG_A]))
+
+    await bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: '/x', salvageOnly: false })
+    mocks.deliverImageToNode.mockClear()
+    mocks.addImageToCanvas.mockClear()
+    // A late idle-timer fire for the same turn: all call_ids already seen → nothing to do.
+    const r = await bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: null, salvageOnly: true })
+
+    expect(r).toEqual({ delivered: 0, orphaned: 0, dropped: 0 })
+    expect(mocks.deliverImageToNode).not.toHaveBeenCalled()
+    expect(mocks.addImageToCanvas).not.toHaveBeenCalled()
+  })
+
+  it('a FAILED salvage does not burn the image — a later Stop hook still claims it (#1751 seen-on-success)', async () => {
+    const bf = makeBackfiller()
+    observeExecuteAnchor(bf, 1, 't1', 's1', 'wf_real', 'nodeA')
+    mocks.readRollout.mockReturnValue(rollout([IMG_A]))
+    // 1) an idle salvage fires but the orphan fails (e.g. session cap) → image must NOT be marked seen.
+    mocks.addImageToCanvas.mockResolvedValueOnce({ ok: false, error: 'session cap reached' })
+    const r1 = await bf.backfillTurn({ turnKey: 't1', rolloutPath: null, salvageOnly: true })
+    expect(r1.orphaned).toBe(0)
+    // 2) the real Stop hook fires → the image is still fresh → claim to the planned node succeeds.
+    const r2 = await bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: '/x', salvageOnly: false })
+    expect(mocks.deliverImageToNode).toHaveBeenCalledTimes(1)
+    expect(mocks.deliverImageToNode.mock.calls[0][0]).toMatchObject({ nodeId: 'nodeA' })
+    expect(r2.delivered).toBe(1)
+  })
+
+  it('an early idle tick (image not flushed yet) keeps turn state for the later hook (#1751 no-delete-on-empty)', async () => {
+    const bf = makeBackfiller()
+    observeExecuteAnchor(bf, 1, 't1', 's1', 'wf_real', 'nodeA')
+    // 1) idle fires mid-generation, before imagegen flushed to rollout → empty, must be a pure no-op.
+    mocks.readRollout.mockReturnValueOnce('')
+    const r1 = await bf.backfillTurn({ turnKey: 't1', rolloutPath: null, salvageOnly: true })
+    expect(r1).toEqual({ delivered: 0, orphaned: 0, dropped: 0 })
+    expect(mocks.addImageToCanvas).not.toHaveBeenCalled()
+    // 2) hook fires after flush → the pending anchor + workflowId survived → claim succeeds.
+    mocks.readRollout.mockReturnValue(rollout([IMG_A]))
+    const r2 = await bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: '/x', salvageOnly: false })
+    expect(mocks.deliverImageToNode).toHaveBeenCalledTimes(1)
+    expect(r2.delivered).toBe(1)
+  })
+
+  it('does nothing (no placement) when no workflowId was ever captured', async () => {
+    const bf = makeBackfiller()
+    // No tool call carried a workflowId this turn.
+    mocks.readRollout.mockReturnValue(rollout([IMG_A]))
+    const r = await bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: '/x', salvageOnly: false })
+    expect(r).toEqual({ delivered: 0, orphaned: 0, dropped: 0 })
+    expect(mocks.deliverImageToNode).not.toHaveBeenCalled()
+    expect(mocks.addImageToCanvas).not.toHaveBeenCalled()
+  })
+})

package/src/__tests__/route.integration.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+
+/**
+ * Opt-in integration test against a REAL running gemus `/api/mcp` route (#1751). Validates the Mode-B
+ * **key-only** contract the proxy + core delivery rely on: Bearer `mak_` auth with **no**
+ * `X-Gemus-Session-Id` header, and addressing by an explicit real `workflowId`.
+ *
+ * Excluded from the default runner (`*.integration.test.ts`) and gated on env so it never runs in CI or
+ * by accident. To run against local dev:
+ *   GEMUS_IT_KEY=mak_... GEMUS_IT_WORKFLOW=<realWorkflowId> \
+ *   pnpm exec vitest run packages/gemus-mcp-proxy/src/__tests__/route.integration.test.ts
+ * (GEMUS_IT_URL defaults to http://localhost:3000/api/mcp.) All calls here are read-only (no mutation).
+ *
+ * connect-per-call invariant: every case opens + closes its own client (fresh connectionNonce, #1744).
+ */
+const KEY = process.env.GEMUS_IT_KEY
+const URL_ = process.env.GEMUS_IT_URL || 'http://localhost:3000/api/mcp'
+const WORKFLOW = process.env.GEMUS_IT_WORKFLOW
+
+/** Key-only client: Bearer only, deliberately NO X-Gemus-Session-Id (the Mode-B contract). */
+async function connectKeyOnly() {
+  const client = new Client({ name: 'gemus-proxy-it', version: '0.1.0' })
+  const transport = new StreamableHTTPClientTransport(new URL(URL_), {
+    requestInit: { headers: { Authorization: `Bearer ${KEY}` } },
+  })
+  await client.connect(transport)
+  return client
+}
+
+describe.skipIf(!KEY)('key-only /api/mcp route (real, opt-in)', () => {
+  it('relays the full tool surface incl. execute/batch_execute (no session header)', async () => {
+    const client = await connectKeyOnly()
+    try {
+      const { tools } = await client.listTools()
+      const names = tools.map((t) => t.name)
+      expect(names).toEqual(expect.arrayContaining(['execute', 'batch_execute', 'canvas_read', 'canvas_edit']))
+    } finally {
+      await client.close()
+    }
+  })
+
+  it('serves resources (skills / knowledge) through the key-only connection', async () => {
+    const client = await connectKeyOnly()
+    try {
+      const { resources } = await client.listResources()
+      // The route exposes skill:// / knowledge:// resources; a tool-only passthrough would drop these.
+      expect(Array.isArray(resources)).toBe(true)
+    } finally {
+      await client.close()
+    }
+  })
+
+  it.skipIf(!WORKFLOW)('addresses a real workflow by explicit workflowId (key-only, no activeContext)', async () => {
+    const client = await connectKeyOnly()
+    try {
+      // canvas_read is read-only; success proves key-only addressing by explicit workflowId works
+      // without a session header (what deliverImageToNode relies on in Mode B).
+      const res = (await client.callTool({ name: 'canvas_read', arguments: { workflowId: WORKFLOW } })) as {
+        isError?: boolean
+      }
+      expect(res.isError).not.toBe(true)
+    } finally {
+      await client.close()
+    }
+  })
+})

package/src/backfill.mjs

@@ -0,0 +1,195 @@
+// @gemus/mcp-proxy — turn-scoped imagegen backfill orchestration (Issue #1751, Mode B key-only).
+//
+// Consumes the shared core (@gemus/codex-backfill-core): taps proxied execute/batch_execute to feed
+// a per-turn ExecuteClaimTracker, then at turn end reads the rollout, claims scavenged images to their
+// planned nodes (key-only deliverImageToNode with a REAL workflowId), and orphans the rest.
+//
+// Turn identity (Step-0.4 real-machine capture, codex 0.142.2): both the tool-call `_meta` and the
+// Stop-hook payload carry `turn_id` + `session_id` (NO thread_id). Turn state is keyed by `turn_id`
+// (each turn = its own tracker); the rollout file is named `-<session_id>.jsonl`, so the idle-timer
+// fallback locates it via findRolloutFile(codexHome, session_id).
+//
+// Two turn-end triggers (see proxy.mjs):
+//   • Stop hook (trusted)  → backfillTurn({ rolloutPath: <transcript_path>, salvageOnly: false }) → claim
+//   • idle-timer fallback  → backfillTurn({ rolloutPath: null,             salvageOnly: true  }) → orphan-only
+// `seen` (session-wide call_id set) makes the two idempotent: whichever runs first marks images seen, so
+// a later trigger no-ops. salvageOnly NEVER calls claim() — mirrors bridge salvage semantics (图不丢, 不认领).
+import * as core from '@gemus/codex-backfill-core'
+
+/**
+ * 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` /
+ * `mcp__gemus__batch_execute` (mirrors codexEventAdapter.normalizeToolName). Without this the
+ * tracker silently no-ops → every image orphans. Non-execute names pass through unchanged.
+ */
+const WIRE_TO_NORMALIZED = {
+  execute: 'mcp__gemus__execute',
+  batch_execute: 'mcp__gemus__batch_execute',
+}
+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).
+export const COMPANION_STEERING = [
+  '# Gemus companion — codex-imagen is auto-backfilled',
+  '',
+  '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:"..."}.)',
+].join('\n')
+
+/**
+ * Mutate an MCP `initialize` RESPONSE in place to append companion steering to `result.instructions`
+ * (the one always-on channel to the model in Mode B). No-op for any other message. Returns true if it
+ * injected (for logging). Only touches the initialize result; everything else relays untouched.
+ */
+export function injectSteering(msg) {
+  const result = msg?.result
+  if (!result || !(result.protocolVersion || result.serverInfo)) return false
+  const existing = typeof result.instructions === 'string' ? result.instructions : ''
+  result.instructions = existing ? `${existing}\n\n${COMPANION_STEERING}` : COMPANION_STEERING
+  return true
+}
+
+/**
+ * @param {object} deps
+ * @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 {(msg: string, obj?: unknown) => void} [deps.log]
+ */
+export function createBackfiller({ server, apiKey, codexHome, 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
+  /** session-wide call_ids that were **successfully placed** → 两个触发路径幂等。**只在交付成功后加入**
+   * （不在尝试前）：否则一次过早/失败的 idle salvage 会把图标记 seen，真正的 Stop hook 就再也认领不到它。 */
+  const seen = new Set()
+
+  function getTurn(turnKey) {
+    let t = turns.get(turnKey)
+    if (!t) {
+      if (turns.size >= TURN_CAP) {
+        const oldest = turns.keys().next().value
+        if (oldest !== undefined) turns.delete(oldest)
+      }
+      t = { tracker: new core.ExecuteClaimTracker(), workflowId: undefined, sessionId: undefined }
+      turns.set(turnKey, t)
+    }
+    return t
+  }
+
+  /** tap: client→server `tools/call` request. jsonrpcId 作 toolCallId 关联 request↔response。 */
+  function observeCall({ jsonrpcId, turnKey, sessionId, name, args }) {
+    if (!turnKey) return
+    const t = getTurn(turnKey)
+    if (sessionId) t.sessionId = sessionId // idle-fallback rollout 定位用
+    // Mode B 必需：真实 workflowId 从 args 捕获（execute/canvas_read 都带；server 无 activeContext 可覆盖）。
+    if (args && typeof args.workflowId === 'string' && args.workflowId) t.workflowId = args.workflowId
+    t.tracker.observe({
+      type: 'tool-call',
+      toolName: normalizeToolName(name),
+      toolCallId: String(jsonrpcId),
+      args,
+    })
+  }
+
+  /** tap: server→client `tools/call` response. resultContent = MCP ContentBlock[]（unwrap 还原结构）。 */
+  function observeResult({ jsonrpcId, turnKey, name, resultContent }) {
+    if (!turnKey) return
+    const t = getTurn(turnKey)
+    t.tracker.observe({
+      type: 'tool-result',
+      toolName: normalizeToolName(name),
+      toolCallId: String(jsonrpcId),
+      result: core.unwrapMcpContent(resultContent),
+    })
+  }
+
+  /** orphan 一张图（Mode B 需真实 workflowId），**只在成功后**标记 seen；返回是否成功。 */
+  async function orphanOne(workflowId, image) {
+    const r = await core.addImageToCanvas({ server, apiKey, workflowId, image })
+    if (r.ok) {
+      seen.add(image.callId)
+      return true
+    }
+    log('backfill: orphan failed', { callId: image.callId, error: r.error })
+    return false
+  }
+
+  /**
+   * turn 末回填。`rolloutPath` 来自 Stop hook（精确文件）；缺省 → findRolloutFile(codexHome, session_id)。
+   * `salvageOnly` = true 时只 orphan（绝不 claim），镜像 bridge salvage。
+   *
+   * **不预先标记 seen、不在空/失败时删除 turn 状态**（#1751 真机 bug 修复）：早期或失败的触发（如 idle
+   * timer 在生成中途误触发、或 session-cap 交付失败）绝不能烧掉图 —— 否则真正的 Stop hook 认领时
+   * fresh 为空。seen 只在成功交付后加入；turn 状态保留供后续 authoritative Stop hook 认领。
+   */
+  async function backfillTurn({ 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)
+    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)' })
+      return { delivered: 0, orphaned: 0, dropped: 0 }
+    }
+
+    const workflowId = t?.workflowId
+    if (!workflowId) {
+      // Mode B 无 activeContext：orphan 也需真实 workflowId 寻址。turn 里任一工具调用都带 workflowId，
+      // 正常不会走到这里；防御性记录并放弃（不烧 seen，后续带 workflowId 的 hook 仍可认领）。
+      log('backfill: no workflowId captured — cannot place images', { turnKey, fresh: fresh.length })
+      return { delivered: 0, orphaned: 0, dropped: 0 }
+    }
+
+    // salvageOnly / 无 tracker → orphan-only（绝不 claim）。
+    if (salvageOnly || !t) {
+      let orphaned = 0
+      for (const image of fresh) if (await orphanOne(workflowId, image)) orphaned++
+      log('backfill: salvage', { turnKey, orphaned, of: fresh.length })
+      return { delivered: 0, orphaned, dropped: 0 }
+    }
+
+    // 认领路径：claim() 保守分配（详见 core），失败 deliver 回退 orphan（图不丢）。seen 只在成功后加。
+    const { claims, orphans, dropped } = t.tracker.claim(fresh)
+    let delivered = 0
+    let orphaned = 0
+    for (const { nodeId, image } of claims) {
+      const r = await core.deliverImageToNode({ server, apiKey, workflowId, nodeId, image })
+      if (r.ok) {
+        seen.add(image.callId)
+        delivered++
+      } else if (await orphanOne(workflowId, image)) {
+        // already_completed / 其它失败 → orphan 保底（镜像 bridge：新图未落节点则至少 image-upload）。
+        orphaned++
+      } else {
+        log('backfill: deliver+orphan both failed', { nodeId, callId: image.callId, error: r.error ?? r.code })
+      }
+    }
+    for (const image of orphans) if (await orphanOne(workflowId, image)) orphaned++
+    log('backfill: claimed', { turnKey, delivered, orphaned, dropped })
+    return { delivered, orphaned, dropped }
+  }
+
+  return { observeCall, observeResult, backfillTurn, _turns: turns, _seen: seen }
+}

package/src/proxy.mjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+// @gemus/mcp-proxy — local stdio<->HTTP MCP proxy for Codex desktop (Issue #1751, P1).
+//
+// Codex (stdio) <-> this proxy <-> remote gemus /api/mcp (streamable HTTP, Bearer mak_ key).
+// The proxy is a TRANSPARENT JSON-RPC passthrough (tools + resources + notifications all relay
+// untouched) that additionally TAPS execute/batch_execute to observe client-delivered image
+// backfill anchors, then at turn end backfills codex imagegen output into the planned gen-* nodes.
+// Codex does no auth for stdio MCP servers, so THIS process owns upstream auth (the user's mak_ key).
+//
+// Turn-end backfill has two triggers:
+//   • Stop hook (trusted) → loopback HTTP POST /backfill { transcript_path, thread_id } → claim path.
+//   • idle-timer fallback (untrusted hook) → salvageOnly (orphan-only). Both idempotent via seen-set.
+//
+// Validated end-to-end on 2026-07-06 (codex-cli 0.142.2, real dev /api/mcp): transparent passthrough
+// of all 12 gemus tools; codex spawns one proxy per session; real tool-calls tapped with workflowId
+// (from arguments) + turn/thread identity (from _meta.x-codex-turn-metadata). Step-0.4: plugin-bundled
+// Stop hook fires (needs /hooks trust); codex does NOT interpolate ${VAR} in MCP env → key is a literal
+// in local `codex mcp add --env`. See docs/plans/1751-codex-desktop-companion.md.
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+import http from 'node:http'
+import os from 'node:os'
+import path from 'node:path'
+import fs from 'node:fs'
+import { randomBytes } from 'node:crypto'
+import { createBackfiller, injectSteering } from './backfill.mjs'
+
+const KEY = process.env.GEMUS_KEY || ''
+const GEMUS_URL = process.env.GEMUS_URL || 'https://gemus.ai/api/mcp'
+const SERVER_ORIGIN = GEMUS_URL.replace(/\/api\/mcp\/?$/, '') // core delivery appends /api/mcp itself
+const CODEX_HOME = process.env.CODEX_HOME || path.join(os.homedir(), '.codex')
+// turn-idle fallback (untrusted-hook path). Default 3min: imagegen alone runs 30-60s with NO MCP tool
+// 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
+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`)
+}
+
+const backfiller = createBackfiller({
+  server: SERVER_ORIGIN,
+  apiKey: KEY,
+  codexHome: CODEX_HOME,
+  log: (msg, obj) => log('BACKFILL', obj ? `${msg} ${JSON.stringify(obj)}` : msg),
+})
+
+// ── turn identity + request↔response correlation ───────────────────────────────────────────────
+// Step-0.4 capture: tool-call `_meta` + Stop-hook payload both carry `turn_id` + `session_id` (no
+// thread_id). Turn state keys on turn_id; session_id locates the rollout in the idle fallback.
+/** in-flight tools/call: jsonrpc id (string) → { turnKey, name } — so the server→client response
+ * (which carries no _meta) can be attributed to its turn + tool. */
+const inflight = new Map()
+/** per-turn idle timer — turn-END fallback when no Stop hook fires (untrusted). Reset on activity. */
+const idleTimers = new Map()
+let sessionId // learned from first tool-call _meta.session_id; used for the hook discovery file
+let discoveryFile // <tmpdir>/gemus-proxy-<sessionId>.json — written once sessionId is known
+
+function metaOf(msg) {
+  const meta = msg?.params?._meta?.['x-codex-turn-metadata']
+  return {
+    turnId: meta?.turn_id || meta?.turnId,
+    sessionId: meta?.session_id || meta?.sessionId,
+  }
+}
+
+function armIdleTimer(turnKey) {
+  if (!turnKey) return
+  const existing = idleTimers.get(turnKey)
+  if (existing) clearTimeout(existing)
+  const timer = setTimeout(() => {
+    idleTimers.delete(turnKey)
+    // salvageOnly fallback: turn went quiet with no Stop hook. Orphan any fresh images (never claim).
+    // seen-set makes this a no-op if a hook already backfilled this turn.
+    backfiller
+      .backfillTurn({ turnKey, rolloutPath: null, salvageOnly: true })
+      .catch((e) => log('IDLE-BACKFILL-ERR', String(e)))
+  }, IDLE_MS)
+  if (typeof timer.unref === 'function') timer.unref() // don't keep the process alive on this timer alone
+  idleTimers.set(turnKey, timer)
+}
+
+function writeDiscoveryOnce() {
+  if (discoveryFile || !sessionId || !hookPort || !hookToken) return
+  discoveryFile = path.join(os.tmpdir(), `gemus-proxy-${sessionId}.json`)
+  try {
+    fs.writeFileSync(discoveryFile, JSON.stringify({ port: hookPort, token: hookToken }))
+    log('DISCOVERY-WRITE', { discoveryFile, port: hookPort })
+  } catch (e) {
+    log('DISCOVERY-ERR', String(e))
+  }
+}
+
+// injectSteering (imported) mutates the initialize response's `instructions` to tell codex not to
+// self-forward imagegen output — the one always-on steering channel in Mode B. See backfill.mjs.
+function steerOnInit(msg) {
+  try {
+    if (injectSteering(msg)) log('STEERING-INJECTED', { instructionsLen: msg.result.instructions.length })
+  } catch (e) {
+    log('STEERING-ERR', String(e))
+  }
+}
+
+// ── taps (do not mutate the relayed messages) ──────────────────────────────────────────────────
+function tapClientToServer(msg) {
+  try {
+    if (msg?.method !== 'tools/call') return
+    const { turnId, sessionId: sid } = metaOf(msg)
+    if (sid && !sessionId) {
+      sessionId = sid
+      writeDiscoveryOnce()
+    }
+    if (turnId) armIdleTimer(turnId)
+    const id = msg.id
+    if (id === undefined || id === null) return // notifications: no response to correlate
+    const name = msg.params?.name || ''
+    inflight.set(String(id), { turnKey: turnId, name })
+    backfiller.observeCall({ jsonrpcId: id, turnKey: turnId, sessionId: sid, name, args: msg.params?.arguments || {} })
+  } catch (e) {
+    log('TAP-C2S-ERR', String(e))
+  }
+}
+
+function tapServerToClient(msg) {
+  try {
+    const id = msg?.id
+    if (id === undefined || id === null) return
+    const pending = inflight.get(String(id))
+    if (!pending) return
+    inflight.delete(String(id))
+    if (!msg.result) return // errors: nothing to observe for claim tracking
+    backfiller.observeResult({
+      jsonrpcId: id,
+      turnKey: pending.turnKey,
+      name: pending.name,
+      resultContent: msg.result?.content,
+    })
+  } catch (e) {
+    log('TAP-S2C-ERR', String(e))
+  }
+}
+
+// ── loopback Stop-hook endpoint (127.0.0.1:<random port> + per-run token) ──────────────────────
+let hookPort
+const hookToken = randomBytes(16).toString('hex')
+const hookServer = http.createServer((req, res) => {
+  if (req.method !== 'POST' || !req.url?.startsWith('/backfill')) {
+    res.writeHead(404).end()
+    return
+  }
+  let body = ''
+  req.on('data', (c) => {
+    body += c
+    if (body.length > 64 * 1024) req.destroy() // trivial DoS guard; payload is tiny JSON
+  })
+  req.on('end', () => {
+    let payload
+    try {
+      payload = JSON.parse(body)
+    } catch {
+      res.writeHead(400).end()
+      return
+    }
+    if (payload?.token !== hookToken) {
+      res.writeHead(403).end()
+      return
+    }
+    // Stop-hook payload (Step-0.4 capture): { session_id, turn_id, transcript_path, ... } — no thread_id.
+    const turnKey = payload.turn_id || payload.turnId
+    const sid = payload.session_id || payload.sessionId
+    const rolloutPath = payload.transcript_path || payload.transcriptPath || null
+    log('HOOK-BACKFILL', { turnKey, sid, rolloutPath })
+    res.writeHead(200).end('ok')
+    // A Stop hook backfilled this turn → cancel its idle-timer fallback (avoid a redundant salvage pass).
+    const timer = idleTimers.get(turnKey)
+    if (timer) { clearTimeout(timer); idleTimers.delete(turnKey) }
+    // Stop hook fires post-flush → claim path (not salvage). Fire-and-forget; never throw.
+    backfiller
+      .backfillTurn({ turnKey, sessionId: sid, rolloutPath, salvageOnly: false })
+      .catch((e) => log('HOOK-BACKFILL-ERR', String(e)))
+  })
+})
+hookServer.on('error', (e) => log('HOOK-SERVER-ERR', String(e)))
+hookServer.listen(0, '127.0.0.1', () => {
+  hookPort = hookServer.address().port
+  log('HOOK-SERVER', { port: hookPort })
+  writeDiscoveryOnce() // in case sessionId was already learned before listen resolved
+})
+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}` } },
+})
+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))) }
+
+// ── 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.
+let shuttingDown = false
+async function shutdown() {
+  if (shuttingDown) return
+  shuttingDown = true
+  for (const t of idleTimers.values()) clearTimeout(t)
+  idleTimers.clear()
+  try { hookServer.close() } catch { /* ignore */ }
+  if (discoveryFile) { try { fs.unlinkSync(discoveryFile) } catch { /* ignore */ } }
+  try { await upstream.terminateSession() } catch { /* ignore */ }
+  try { await upstream.close() } catch { /* ignore */ }
+  process.exit(0)
+}
+stdio.onclose = () => { log('stdio-close', ''); void shutdown() }
+upstream.onclose = () => { log('http-close', '') }
+stdio.onerror = (e) => log('stdio-err', String(e))
+upstream.onerror = (e) => log('http-err', String(e))
+process.on('SIGTERM', shutdown)
+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 })