@gemus/mcp-proxy 0.1.8 → 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()
-  })
-})

package/src/__tests__/failFast.test.ts

@@ -1,254 +0,0 @@
-/**
- * @gemus/mcp-proxy fail-fast (#2068) — single-pass upstream-disconnect correlation.
- *
- * Pure logic; the socket is an injected `realFetch` returning controllable `Response`s. Cases that
- * involve the final-safety timer use fake timers with advanceTimersByTimeAsync (lesson: fake timers
- * + real reader.read() promises need the async advance to flush continuations).
- */
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
-import { parseRequestIds, isCodexOriginated, createSseIdScanner, createFailFast, isJsonRpcResponse } from '../failFast.mjs'
-
-const enc = new TextEncoder()
-
-/** A response body that emits the given SSE frames then closes. */
-function bodyOf(...frames: string[]): ReadableStream<Uint8Array> {
-  return new ReadableStream<Uint8Array>({
-    start(c) {
-      for (const f of frames) c.enqueue(enc.encode(f))
-      c.close()
-    },
-  })
-}
-/** A response body that never emits and never closes (zombie stream). */
-function neverBody(): ReadableStream<Uint8Array> {
-  return new ReadableStream<Uint8Array>({ start() {} })
-}
-function sseRes(body: ReadableStream<Uint8Array> | null, init?: { status?: number; contentType?: string }) {
-  const status = init?.status ?? 200
-  return new Response(body, { status, headers: { 'content-type': init?.contentType ?? 'text/event-stream' } })
-}
-function resultFrame(id: number | string): string {
-  return `event: message\ndata: ${JSON.stringify({ jsonrpc: '2.0', id, result: { ok: true } })}\n\n`
-}
-function post(id: number | string, method = 'tools/call') {
-  return { method: 'POST', body: JSON.stringify({ jsonrpc: '2.0', id, method, params: {} }) }
-}
-async function drain(res: Response): Promise<void> {
-  const r = res.body!.getReader()
-  for (;;) { const { done } = await r.read(); if (done) break }
-}
-
-describe('parseRequestIds', () => {
-  it('extracts the id from a POST JSON-RPC request', () => {
-    expect(parseRequestIds(post(42))).toEqual([42])
-  })
-  it('extracts all ids from a batch', () => {
-    const body = JSON.stringify([
-      { jsonrpc: '2.0', id: 1, method: 'a' },
-      { jsonrpc: '2.0', id: 2, method: 'b' },
-    ])
-    expect(parseRequestIds({ method: 'POST', body })).toEqual([1, 2])
-  })
-  it('returns [] for GET / DELETE / bodyless requests', () => {
-    expect(parseRequestIds({ method: 'GET' })).toEqual([])
-    expect(parseRequestIds({ method: 'DELETE' })).toEqual([])
-    expect(parseRequestIds({ method: 'POST' })).toEqual([])
-  })
-  it('returns [] for non-JSON body and for notifications (no id)', () => {
-    expect(parseRequestIds({ method: 'POST', body: 'not json' })).toEqual([])
-    expect(parseRequestIds({ method: 'POST', body: JSON.stringify({ jsonrpc: '2.0', method: 'x' }) })).toEqual([])
-  })
-})
-
-describe('isCodexOriginated', () => {
-  it.each([
-    [42, true],
-    ['abc', true],
-    ['gemus-bf-3', false],
-    ['gemus-ping-9', false],
-    [null, false],
-    [undefined, false],
-  ])('id=%s → %s', (id, expected) => {
-    expect(isCodexOriginated(id as never)).toBe(expected)
-  })
-})
-
-describe('isJsonRpcResponse', () => {
-  it('is true for a result/error response, false for a request or notification', () => {
-    expect(isJsonRpcResponse({ id: 1, result: {} })).toBe(true)
-    expect(isJsonRpcResponse({ id: 1, error: {} })).toBe(true)
-    expect(isJsonRpcResponse({ id: 1, method: 'elicitation/create', params: {} })).toBe(false) // server→client request
-    expect(isJsonRpcResponse({ method: 'notifications/x' })).toBe(false)
-    expect(isJsonRpcResponse(null)).toBe(false)
-  })
-})
-
-describe('createSseIdScanner', () => {
-  it('yields the id of a complete RESPONSE frame; ignores comment lines', () => {
-    const s = createSseIdScanner()
-    expect(s.push(enc.encode(': keepalive\n\n'))).toEqual([])
-    expect(s.push(enc.encode(resultFrame(7)))).toEqual([7])
-  })
-  it('does NOT yield a server→client REQUEST id (has a method) — avoids id-collision premature settle', () => {
-    const s = createSseIdScanner()
-    const reqFrame = `event: message\ndata: ${JSON.stringify({ jsonrpc: '2.0', id: 3, method: 'elicitation/create', params: {} })}\n\n`
-    expect(s.push(enc.encode(reqFrame))).toEqual([])
-  })
-  it('buffers a half-frame split across chunks until its boundary arrives', () => {
-    const s = createSseIdScanner()
-    const frame = resultFrame(5)
-    const mid = Math.floor(frame.length / 2)
-    expect(s.push(enc.encode(frame.slice(0, mid)))).toEqual([])
-    expect(s.push(enc.encode(frame.slice(mid)))).toEqual([5])
-  })
-  it('handles CRLF line endings (normalizes to LF)', () => {
-    const s = createSseIdScanner()
-    const crlf = `event: message\r\ndata: ${JSON.stringify({ jsonrpc: '2.0', id: 8, result: {} })}\r\n\r\n`
-    expect(s.push(enc.encode(crlf))).toEqual([8])
-  })
-  it('ignores non-JSON data payloads', () => {
-    const s = createSseIdScanner()
-    expect(s.push(enc.encode('data: not-json\n\n'))).toEqual([])
-  })
-})
-
-describe('createFailFast.fetch', () => {
-  it('injects a JSON-RPC error when the stream closes before the result', async () => {
-    const onLost = vi.fn()
-    const realFetch = vi.fn(async () => sseRes(bodyOf(': keepalive\n\n'))) // no result frame → lost
-    const ff = createFailFast({ onLost, realFetch })
-
-    const res = await ff.fetch('u', post(42))
-    await drain(res)
-
-    expect(onLost).toHaveBeenCalledTimes(1)
-    expect(onLost.mock.calls[0][0]).toBe(42)
-    expect(ff.failedIds.has('42')).toBe(true)
-  })
-
-  it('does NOT inject an error when the result crosses the wire before close', async () => {
-    const onLost = vi.fn()
-    const realFetch = vi.fn(async () => sseRes(bodyOf(resultFrame(42))))
-    const ff = createFailFast({ onLost, realFetch })
-
-    const res = await ff.fetch('u', post(42))
-    await drain(res)
-
-    expect(onLost).not.toHaveBeenCalled()
-    expect(ff.failedIds.has('42')).toBe(false)
-  })
-
-  it('fails fast immediately when realFetch throws before any response', async () => {
-    const onLost = vi.fn()
-    const realFetch = vi.fn(async () => { throw new Error('ECONNRESET') })
-    const ff = createFailFast({ onLost, realFetch })
-
-    await expect(ff.fetch('u', post(7))).rejects.toThrow('ECONNRESET')
-    expect(onLost).toHaveBeenCalledWith(7, expect.stringContaining('upstream fetch failed'))
-    expect(realFetch).toHaveBeenCalledTimes(1) // must NOT retry — a 2nd fetch could execute the tool
-  })
-
-  it('fails fast on a non-ok HTTP response', async () => {
-    const onLost = vi.fn()
-    const realFetch = vi.fn(async () => sseRes(null, { status: 404, contentType: 'application/json' }))
-    const ff = createFailFast({ onLost, realFetch })
-
-    await ff.fetch('u', post(7))
-    expect(onLost).toHaveBeenCalledWith(7, 'upstream HTTP 404')
-  })
-
-  it('passes GET and DELETE through untouched (no body → no monitoring, no onLost)', async () => {
-    const onLost = vi.fn()
-    const getRes = sseRes(bodyOf())
-    const realFetch = vi.fn(async () => getRes)
-    const ff = createFailFast({ onLost, realFetch })
-
-    const g = await ff.fetch('u', { method: 'GET' })
-    const d = await ff.fetch('u', { method: 'DELETE' })
-    expect(g).toBe(getRes)
-    expect(d).toBe(getRes)
-    expect(onLost).not.toHaveBeenCalled()
-  })
-
-  it('does not track internal gemus-bf-* / gemus-ping-* ids', async () => {
-    const onLost = vi.fn()
-    const realFetch = vi.fn(async () => sseRes(bodyOf(': keepalive\n\n'))) // closes with no result
-    const ff = createFailFast({ onLost, realFetch })
-
-    await drain(await ff.fetch('u', post('gemus-bf-1')))
-    await drain(await ff.fetch('u', post('gemus-ping-2')))
-    expect(onLost).not.toHaveBeenCalled()
-  })
-
-  it('degrades to plain passthrough if internal logic throws', async () => {
-    const onLost = vi.fn()
-    const badRes = { ok: true, status: 200, headers: { get() { throw new Error('boom') } }, body: null } as unknown as Response
-    const realFetch = vi.fn(async () => badRes)
-    const ff = createFailFast({ onLost, realFetch })
-
-    const res = await ff.fetch('u', post(1))
-    expect(res).toBe(badRes)              // returns the response we ALREADY have — no re-fetch
-    expect(realFetch).toHaveBeenCalledTimes(1)
-    expect(onLost).not.toHaveBeenCalled()
-    ff.dispose()
-  })
-
-  it('isolates concurrent requests — disconnecting one does not affect the other', async () => {
-    const onLost = vi.fn()
-    const realFetch = vi
-      .fn()
-      .mockResolvedValueOnce(sseRes(bodyOf(': keepalive\n\n')))   // id 1 → dies with no result
-      .mockResolvedValueOnce(sseRes(bodyOf(resultFrame(2))))      // id 2 → delivers
-    const ff = createFailFast({ onLost, realFetch })
-
-    await drain(await ff.fetch('u', post(1)))
-    await drain(await ff.fetch('u', post(2)))
-
-    expect(onLost).toHaveBeenCalledTimes(1)
-    expect(onLost.mock.calls[0][0]).toBe(1)
-  })
-
-  describe('idle safety timeout', () => {
-    beforeEach(() => vi.useFakeTimers())
-    afterEach(() => vi.useRealTimers())
-
-    it('injects an error for a zombie connection that never emits a byte', async () => {
-      const onLost = vi.fn()
-      const realFetch = vi.fn(async () => sseRes(neverBody()))
-      const ff = createFailFast({ onLost, realFetch, idleTimeoutMs: 120_000 })
-
-      await ff.fetch('u', post(99)) // never emits → idle timer is never reset
-      expect(onLost).not.toHaveBeenCalled()
-      await vi.advanceTimersByTimeAsync(120_000)
-      expect(onLost).toHaveBeenCalledWith(99, expect.stringContaining('idle'))
-      ff.dispose()
-    })
-
-    it('does NOT kill a healthy-but-slow stream — heartbeat bytes reset the idle timer', async () => {
-      const onLost = vi.fn()
-      let ctl!: ReadableStreamDefaultController<Uint8Array>
-      const body = new ReadableStream<Uint8Array>({ start(c) { ctl = c } })
-      const realFetch = vi.fn(async () => sseRes(body))
-      const ff = createFailFast({ onLost, realFetch, idleTimeoutMs: 100 })
-
-      const res = await ff.fetch('u', post(1))
-      const reader = res.body!.getReader()
-
-      // Keepalive every 60ms (< 100ms idle) for 300ms total — each read touches → never fires.
-      for (let i = 0; i < 5; i++) {
-        ctl.enqueue(enc.encode(': keepalive\n\n'))
-        await reader.read()
-        await vi.advanceTimersByTimeAsync(60)
-      }
-      expect(onLost).not.toHaveBeenCalled() // survived 300ms > idleTimeout because bytes kept flowing
-
-      // Now the result arrives and the stream closes → still no fail-fast.
-      ctl.enqueue(enc.encode(resultFrame(1)))
-      await reader.read()
-      ctl.close()
-      await reader.read()
-      expect(onLost).not.toHaveBeenCalled()
-      ff.dispose()
-    })
-  })
-})