@gemus/mcp-proxy 0.1.9 → 0.1.10

package/src/__tests__/backfill.test.ts

@@ -1,394 +0,0 @@
-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(),
-  readGeneratedImageFiles: 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,
-    readGeneratedImageFiles: mocks.readGeneratedImageFiles,
-  }
-})
-
-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')
-  // Default: generated_images unavailable → backfill falls back to the rollout source (existing tests).
-  mocks.readGeneratedImageFiles.mockReset().mockReturnValue({ available: false, images: [], failedCallIds: [] })
-})
-
-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 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('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)
-    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('serializes concurrent passes so a racing salvage does not double-place an in-flight claim (#1751)', async () => {
-    // Real-machine bug (dev.log 1400–1544): a claim pass (Stop hook) and a salvage pass (idle timer)
-    // ran concurrently over the same session rollout. Because `seen` is only marked AFTER each slow
-    // awaited deliver, the salvage pass read the still-in-flight images as "fresh" and orphaned them —
-    // the same image landed BOTH on its planned gen node AND as a duplicate image-upload node.
-    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]))
-
-    // deliver resolves only when released — models the 6-20s awaited media job seen in the logs.
-    let releaseDeliver!: () => void
-    const gate = new Promise<void>((res) => {
-      releaseDeliver = res
-    })
-    mocks.deliverImageToNode.mockImplementation(async () => {
-      await gate
-      return { ok: true, status: 'processing' }
-    })
-
-    // Fire the claim pass (parks on the deliver gate), then a racing salvage pass — do NOT await between.
-    const claimPass = bf.backfillTurn({ turnKey: 't1', sessionId: 's1', rolloutPath: '/x', salvageOnly: false })
-    const salvagePass = bf.backfillTurn({ turnKey: 't1', rolloutPath: null, salvageOnly: true })
-    releaseDeliver()
-    const [claimResult, salvageResult] = await Promise.all([claimPass, salvagePass])
-
-    // Both images delivered to their planned nodes; the racing salvage placed NO duplicate orphans.
-    expect(claimResult).toEqual({ delivered: 2, orphaned: 0, dropped: 0 })
-    expect(salvageResult).toEqual({ delivered: 0, orphaned: 0, dropped: 0 })
-    expect(mocks.addImageToCanvas).not.toHaveBeenCalled()
-  })
-
-  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()
-  })
-})
-
-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: 'call_current', 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: 'call_current' },
-    })
-  })
-
-  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)
-  })
-
-  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()
-  })
-})