Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
30.6 KB
Raw Blame
import { afterEach, describe, expect, it, vi } from 'vitest'
import { createCanvas } from '@napi-rs/canvas'
import * as fs from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { hashCanonicalCodexRequest } from '@clerum/llm-provider-attempt-contract'
import { LlmPortAdapter } from '../core/adapters/llmPortAdapter'
import type { NativeToolConfig } from '../core/interfaces'
import { appendToolResults } from '../core/orchestration/toolUseLoopMessages'
import { NativeToolRegistry } from '../core/tools/nativeToolRegistry'
import type { Attachment, ChatMessage, ToolResult } from '../core/types'
import { realPngOfDecodedBytesBase64 } from '../llm/__tests__/codexImageFixtures'
import { ClaudeProvider } from '../llm/claude'
import { CodexSubscriptionProvider } from '../llm/codexSubscription'
import type { ImageInputResolver } from '../llm/imageInput'
import { OpenAIProvider } from '../llm/openai'
import { OpenAICompatibleProvider } from '../llm/openaiCompatible'
import type { LlmProvider } from '../llm/registryCore'
import type { SingleTurnProvider } from '../llm/types'
import { VisualInputBudget } from '../visualInput/policy'
import { projectGfsApproval } from '../visualInput/suspension'
import { GfsDownloadStore } from './gfsDownloadStore'

const { sdkCreate, clientFactory } = vi.hoisted(() => ({
  sdkCreate: vi.fn(),
  clientFactory: vi.fn(),
}))

// statfs reports the volume sized to its free space, so the disk's occupancy
// never meets the store's free-space floor.
vi.mock('node:fs/promises', async original => {
  const actual = await original<typeof fs>()
  const { freeSpaceSizedStatfs } = await import('../__tests__/fixtures/gfsStoreTestKit')
  return { ...actual, statfs: freeSpaceSizedStatfs(actual.statfs) }
})

// Only external transport boundaries are replaced. Production client, tool,
// native adapter, message construction and provider serialization all execute.
vi.mock('openai', () => ({
  default: class {
    chat = { completions: { create: sdkCreate } }
  },
}))
vi.mock('./gfsClient', async importOriginal => ({
  ...(await importOriginal<typeof import('./gfsClient')>()),
  getGfsToolScopes: () => new Set(['gfs.read']),
  createGfscClient: clientFactory,
}))

const rid = '1234567890abcdef1234567890abcdef'
const uri = `gfs://main/${rid}`
const model = 'example/vision-model'
type CatalogState = 'supported' | 'unsupported' | 'unknown' | 'missing' | 'codex-present'
const config: NativeToolConfig = {
  workspacePath: '/tmp',
  shellTimeout: 5000,
  toolTimeout: 60000,
  toolProgressInterval: 0,
  httpAllowlist: [],
  envAllowlist: [],
  memoryMaxSize: 1048576,
}
const stores: GfsDownloadStore[] = []
const temporaryRoots: string[] = []

function codexFixture() {
  const authorize = vi.fn(async (input: { request: unknown; requestHash: string }) => {
    const canonical = hashCanonicalCodexRequest(input.request)
    if (!canonical.ok) throw new Error(`invalid unit wire request: ${canonical.code}`)
    expect(input.requestHash).toBe(canonical.value.requestHash)
    return {
      providerAttemptId: 'unit-attempt',
      requestHash: input.requestHash,
      executionTicket: 'unit-only-execution-ticket',
      expiresAt: '2099-01-01T00:00:00.000Z',
    }
  })
  const stream = vi.fn(async (_input: { request: unknown; requestHash: string }) => ({
    text: 'seen',
    toolCalls: [],
    outcome: 'success' as const,
  }))
  const provider = new CodexSubscriptionProvider('gpt-5.6-luna', {
    authorizer: { authorize },
    proxy: { stream },
    attemptContext: () => ({ policyRevision: 1, policyHash: 'b'.repeat(64), hostRef: 'chatllm' }),
  } as never)
  return {
    authorize,
    stream,
    llm: { provider, model: 'gpt-5.6-luna', name: 'codex-subscription' as const },
  }
}

async function setup(
  bytes: Buffer,
  options: {
    name?: string
    catalogState?: CatalogState
    llm?: { provider: SingleTurnProvider; model: string; name: LlmProvider }
    managed?: boolean
  } = {}
) {
  const { createGfscClient } = await vi.importActual<typeof import('./gfsClient')>('./gfsClient')
  const gfsFetch = vi.fn(async (url: string) =>
    url.includes('/content?')
      ? new Response(new Uint8Array(bytes), {
          headers: {
            'content-type': 'application/octet-stream',
            'content-length': String(bytes.length),
            'x-gfs-uri': uri,
            'x-gfs-version': '7',
          },
        })
      : new Response(
          JSON.stringify({
            ok: true,
            data: {
              resourceId: rid,
              rid,
              drive: 'main',
              gfsUri: uri,
              version: 7,
              kind: 'file',
              name: options.name ?? 'neutral.png',
              bytes: bytes.length,
            },
          }),
          { headers: { 'content-type': 'application/json' } }
        )
  )
  clientFactory.mockReturnValue(
    createGfscClient(
      {
        get: () => undefined,
        readFile: async () => 'integration-only-identity',
        fetch: gfsFetch,
      },
      { maxRetryWaitMs: config.toolTimeout, random: () => 0 }
    )
  )
  const metadataFetch = vi.fn(
    async (_url: string, _init?: RequestInit) =>
      new Response(
        JSON.stringify({
          data: {
            id: model,
            architecture: { input_modalities: ['text', 'image'] },
          },
        }),
        { headers: { 'content-type': 'application/json' } }
      )
  )
  vi.stubGlobal('fetch', metadataFetch)
  sdkCreate.mockResolvedValue({
    choices: [{ message: { content: 'Done' }, finish_reason: 'stop' }],
    usage: { prompt_tokens: 10, completion_tokens: 2, total_tokens: 12 },
  })
  const provider =
    options.llm?.provider ??
    new OpenAICompatibleProvider(
      {
        id: 'openrouter',
        baseURL: 'https://openrouter.ai/api/v1',
        defaultModel: model,
      },
      'integration-only-provider-identity',
      model
    )
  const budget = new VisualInputBudget()
  let catalogState = options.catalogState ?? 'supported'
  const evidence = {
    source: 'curated' as const,
    reference: 'https://example.com/image-input',
    checkedAt: '2026-09-18T00:00:00Z',
  }
  const imageInputResolver: ImageInputResolver = () => {
    if (catalogState === 'missing') return undefined
    if (catalogState === 'codex-present') return { capability: undefined }
    if (catalogState === 'unknown') return { capability: { state: 'unknown' } }
    return { capability: { state: catalogState, evidence } }
  }
  const adapter = new LlmPortAdapter(
    provider,
    options.llm?.model ?? model,
    options.llm?.name ?? 'openrouter',
    undefined,
    undefined,
    undefined,
    undefined,
    undefined,
    imageInputResolver
  )
  let managed:
    | {
        store: GfsDownloadStore
        deliveryAvailable: boolean
        callerIdentity: string
        callerWorkspacePath: string
        retentionOwnerId: string
      }
    | undefined
  if (options.managed) {
    const root = await fs.mkdtemp(join(tmpdir(), 'gfs-image-wire-'))
    temporaryRoots.push(root)
    const callerWorkspacePath = join(root, 'users', 'unit-caller')
    await fs.mkdir(callerWorkspacePath, { recursive: true, mode: 0o700 })
    const store = new GfsDownloadStore(root)
    await store.initialize()
    stores.push(store)
    managed = {
      store,
      deliveryAvailable: true,
      callerWorkspacePath,
      callerIdentity: 'unit-caller',
      retentionOwnerId: 'gfs-image-integration-task',
    }
  }
  const tool = new NativeToolRegistry(
    config,
    'gfs-image-integration',
    undefined,
    undefined,
    undefined,
    undefined,
    undefined,
    undefined,
    undefined,
    undefined,
    undefined,
    undefined,
    options.llm?.name,
    managed
  ).get('clerum__gfs_read')!
  const output = await tool.execute(
    { drive: 'main', resourceId: rid },
    {
      onOutput: () => {},
      timeoutMs: 10000,
      visualInput: { budget, resolveCapability: signal => adapter.getImageInputCapability(signal) },
    }
  )
  const result: ToolResult = { ...output, name: 'clerum__gfs_read', tool_call_id: 'read-image' }
  const messages: ChatMessage[] = [
    {
      role: 'assistant',
      content: '',
      tool_calls: [
        {
          id: 'read-image',
          name: 'clerum__gfs_read',
          arguments: { drive: 'main', resourceId: rid },
        },
      ],
    },
  ]
  const collected: Attachment[] = []
  appendToolResults(messages, [result], collected)
  return {
    adapter,
    messages,
    output,
    gfsFetch,
    metadataFetch,
    budget,
    collected,
    tool,
    setCatalogState: (state: CatalogState) => {
      catalogState = state
    },
  }
}

afterEach(async () => {
  for (const store of stores.splice(0)) {
    await store
      .releaseReceiptOwner('gfs-image-integration-task', 'unit-caller')
      .catch(() => undefined)
    await store.close()
  }
  for (const root of temporaryRoots.splice(0)) await fs.rm(root, { recursive: true, force: true })
  vi.unstubAllGlobals()
  vi.clearAllMocks()
})

describe('GFS bytes to actual provider request', () => {
  it('preserves a native-decoded managed PNG beyond 3 MiB in the actual canonical Codex wire', async () => {
    const transport = codexFixture()
    const bytes = Buffer.from(realPngOfDecodedBytesBase64(3 * 1024 * 1024 + 1), 'base64')
    const subject = await setup(bytes, {
      managed: true,
      llm: transport.llm,
      catalogState: 'codex-present',
    })
    const receipt = JSON.parse(subject.output.content)
    expect(receipt).toMatchObject({
      delivery: 'workspace_file',
      sizeBytes: bytes.byteLength,
      visualDelivery: 'included',
      usage: { visualDelivery: 'included' },
    })
    expect(receipt.path).toMatch(/^\.gfs-downloads\//)
    const original = structuredClone(subject.messages)
    await subject.adapter.completeWithTools({ messages: subject.messages, tools: [] })
    const authorized = transport.authorize.mock.calls[0]![0]
    const wire = authorized.request as {
      messages: Array<{ contentParts?: Array<{ type: string; data?: string }> }>
    }
    expect(
      wire.messages
        .flatMap(message => message.contentParts ?? [])
        .find(part => part.type === 'image')?.data
    ).toBe(bytes.toString('base64'))
    expect(transport.stream.mock.calls[0]![0]).toMatchObject({
      request: authorized.request,
      requestHash: authorized.requestHash,
    })
    expect(subject.messages).toEqual(original)
    subject.budget.close()
  })
  it.each(['openai', 'claude'] as const)(
    'delivers a native-decoded managed PNG beyond 3 MiB through the official %s instance',
    async type => {
      const create = vi.fn(async (_request: unknown) => ({
        content: [{ type: 'text', text: 'seen' }],
        stop_reason: 'end_turn',
        usage: { input_tokens: 1, output_tokens: 1 },
      }))
      const targetModel = type === 'openai' ? 'gpt-4.1' : 'claude-sonnet-4-6'
      const provider =
        type === 'openai'
          ? new OpenAIProvider(
              {
                baseURL: 'https://api.openai.com/v1',
                chat: { completions: { create: sdkCreate } },
              } as never,
              targetModel
            )
          : new ClaudeProvider(
              { baseURL: 'https://api.anthropic.com', messages: { create } } as never,
              targetModel
            )
      const bytes = Buffer.from(realPngOfDecodedBytesBase64(3 * 1024 * 1024 + 1), 'base64')
      const subject = await setup(bytes, {
        managed: true,
        llm: { provider, model: targetModel, name: type },
      })
      expect(JSON.parse(subject.output.content)).toMatchObject({
        delivery: 'workspace_file',
        sizeBytes: bytes.byteLength,
        visualDelivery: 'included',
        usage: { visualDelivery: 'included' },
      })
      const original = structuredClone(subject.messages)
      await subject.adapter.completeWithTools({ messages: subject.messages, tools: [] })
      const request = type === 'openai' ? sdkCreate.mock.calls[0]![0] : create.mock.calls[0]![0]
      const content = (request as { messages: Array<{ content: unknown }> }).messages.flatMap(
        message => (Array.isArray(message.content) ? message.content : [])
      )
      if (type === 'openai') {
        expect(content.find(part => part.type === 'image_url')?.image_url.url).toBe(
          `data:image/png;base64,${bytes.toString('base64')}`
        )
      } else {
        expect(content.find(part => part.type === 'image')?.source).toEqual({
          type: 'base64',
          media_type: 'image/png',
          data: bytes.toString('base64'),
        })
      }
      expect(subject.messages).toEqual(original)
      subject.budget.close()
    }
  )
  it.each(['image/png', 'image/jpeg'] as const)(
    'delivers %s through the verified official OpenAI instance and catalog vision evidence',
    async mime => {
      const model = 'gpt-4.1'
      // Only the SDK HTTP boundary is doubled; no credential or catalog service.
      const client = {
        baseURL: 'https://api.openai.com/v1',
        chat: { completions: { create: sdkCreate } },
      }
      const canvas = createCanvas(8, 8)
      canvas.getContext('2d').fillRect(1, 1, 4, 4)
      const bytes =
        mime === 'image/png' ? canvas.toBuffer('image/png') : canvas.toBuffer('image/jpeg')
      const subject = await setup(bytes, {
        llm: {
          provider: new OpenAIProvider(client as never, model),
          model,
          name: 'openai',
        },
      })
      expect(JSON.parse(subject.output.content).delivery).toBe('image_input')
      await subject.adapter.completeWithTools({ messages: subject.messages, tools: [] })
      expect(subject.metadataFetch).not.toHaveBeenCalled()
      const request = sdkCreate.mock.calls[0][0]
      const images = request.messages
        .flatMap((message: any) => (Array.isArray(message.content) ? message.content : []))
        .filter((part: any) => part.type === 'image_url')
      expect(images).toEqual([
        {
          type: 'image_url',
          image_url: { url: `data:${mime};base64,${bytes.toString('base64')}` },
        },
      ])
      expect(request.model).toBe(model)
      subject.budget.close()
    }
  )

  it('supports an official OpenAI instance with catalog-supported vision beyond the old model allowlist', async () => {
    const client = {
      baseURL: 'https://api.openai.com/v1',
      chat: { completions: { create: sdkCreate } },
    }
    const provider = new OpenAIProvider(client as never, 'future-vision-model')
    const bytes = createCanvas(2, 2).toBuffer('image/png')
    const subject = await setup(bytes, {
      llm: { provider, model: 'future-vision-model', name: 'openai' },
    })

    expect(JSON.parse(subject.output.content).delivery).toBe('image_input')
    await subject.adapter.completeWithTools({ messages: subject.messages, tools: [] })
    expect(JSON.stringify(sdkCreate.mock.calls[0][0])).toContain(bytes.toString('base64'))
    expect(subject.metadataFetch).not.toHaveBeenCalled()
    subject.budget.close()
  })

  it('returns a reference when the catalog omits a documented vision model', async () => {
    const client = {
      baseURL: 'https://api.openai.com/v1',
      chat: { completions: { create: sdkCreate } },
    }
    const provider = new OpenAIProvider(client as never, 'gpt-4.1')
    const subject = await setup(createCanvas(2, 2).toBuffer('image/png'), {
      catalogState: 'missing',
      llm: { provider, model: 'gpt-4.1', name: 'openai' },
    })

    expect(JSON.parse(subject.output.content)).toMatchObject({
      delivery: 'reference_only',
      reason: 'model_image_input_unknown',
    })
    expect(subject.output.attachments).toBeUndefined()
    expect(sdkCreate).not.toHaveBeenCalled()
    subject.budget.close()
  })

  it('withholds an admitted GFS image if catalog support is revoked before dispatch', async () => {
    const transport = codexFixture()
    const subject = await setup(createCanvas(2, 2).toBuffer('image/png'), {
      llm: transport.llm,
      catalogState: 'codex-present',
    })
    expect(JSON.parse(subject.output.content).delivery).toBe('image_input')
    subject.setCatalogState('missing')

    await subject.adapter.completeWithTools({ messages: subject.messages, tools: [] })

    expect(
      subject.messages.some(message => message.contentParts?.some(part => part.type === 'image'))
    ).toBe(true)
    const sentRequest = transport.authorize.mock.calls[0]![0].request as {
      messages: Array<{ role: string; content: string }>
    }
    expect(JSON.stringify(sentRequest)).not.toContain('"type":"image"')
    const sentTool = sentRequest.messages.find(
      (message: { role: string }) => message.role === 'tool'
    )
    expect(JSON.parse(sentTool!.content)).toMatchObject({
      delivery: 'reference_only',
      reason: 'model_image_input_unavailable',
    })
    subject.budget.close()
  })

  it('delivers a GFS image through Codex V2 for a present catalog row', async () => {
    const { authorize, stream, llm } = codexFixture()
    const bytes = createCanvas(2, 2).toBuffer('image/png')
    const subject = await setup(bytes, {
      catalogState: 'codex-present',
      llm,
    })

    expect(JSON.parse(subject.output.content).delivery).toBe('image_input')
    await subject.adapter.completeWithTools({ messages: subject.messages, tools: [] })

    const authorized = authorize.mock.calls[0]![0].request as {
      messages: Array<{ contentParts?: Array<{ type: string }> }>
    }
    const image = authorized.messages
      .flatMap((message: { contentParts?: Array<{ type: string }> }) => message.contentParts ?? [])
      .find((part: { type: string }) => part.type === 'image')
    expect(image).toMatchObject({
      type: 'image',
      data: bytes.toString('base64'),
      source: { kind: 'tool', toolCallId: 'read-image' },
    })
    expect(stream).toHaveBeenCalledOnce()
    subject.budget.close()
  })

  it.each([
    ['image/png', false],
    ['image/jpeg', false],
    ['image/png', true],
    ['image/jpeg', true],
  ] as const)(
    'delivers %s through the verified official Claude instance, cache=%s',
    async (mime, cache) => {
      const targetModel = 'claude-sonnet-4-6'
      // Credential-free SDK boundary double. The production provider serializer,
      // client/tool registry and loop still execute.
      const create = vi.fn(async () => ({
        content: [{ type: 'text', text: 'Done' }],
        stop_reason: 'end_turn',
        usage: { input_tokens: 10, output_tokens: 2 },
      }))
      const client = { baseURL: 'https://api.anthropic.com', messages: { create } }
      const canvas = createCanvas(8, 8)
      canvas.getContext('2d').fillRect(1, 1, 4, 4)
      const bytes =
        mime === 'image/png' ? canvas.toBuffer('image/png') : canvas.toBuffer('image/jpeg')
      const subject = await setup(bytes, {
        llm: {
          provider: new ClaudeProvider(client as never, targetModel),
          model: targetModel,
          name: 'claude',
        },
      })
      expect(subject.output.is_error).toBe(false)
      await subject.adapter.completeWithTools({
        messages: subject.messages,
        tools: [],
        ...(cache
          ? {
              systemPromptParts: {
                stable: 'system instructions',
                context: 'context',
                stableHash: 'fixture',
                contextHash: 'fixture',
              },
            }
          : {}),
      })
      expect(subject.metadataFetch).not.toHaveBeenCalled()
      const request = (create.mock.calls as unknown as Array<[Record<string, any>]>)[0][0]
      const blocks = request.messages.flatMap((m: any) =>
        Array.isArray(m.content) ? m.content : []
      )
      expect(blocks.filter((b: any) => b.type === 'image')).toEqual([
        {
          type: 'image',
          source: { type: 'base64', media_type: mime, data: bytes.toString('base64') },
        },
      ])
      expect(JSON.stringify(blocks.filter((b: any) => b.type !== 'image'))).not.toContain(
        bytes.toString('base64')
      )
      if (cache) expect(request.system[0].cache_control).toEqual({ type: 'ephemeral' })
      subject.budget.close()
    }
  )
  it.each(['unchanged', 'replaced', 'revoked'] as const)(
    'requires a new authorized read after suspension when the resource is %s',
    async state => {
      const original = createCanvas(2, 2).toBuffer('image/png')
      const transport = codexFixture()
      const subject = await setup(original, { llm: transport.llm, catalogState: 'codex-present' })
      const restored = projectGfsApproval({
        request_id: 'approval',
        tool_name: 'shell_exec',
        tool_call_id: 'pending-action',
        parameters: { command: 'echo done' },
        description: 'pending action',
        context_snapshot: subject.messages,
      })
      expect(JSON.stringify(restored)).not.toContain(original.toString('base64'))
      expect(JSON.stringify(restored)).toContain('new_gfs_read_required_after_suspension')
      expect(subject.gfsFetch).toHaveBeenCalledTimes(2)
      const replacement = createCanvas(3, 3).toBuffer('image/png')
      if (state === 'revoked')
        subject.gfsFetch.mockResolvedValueOnce(new Response('denied', { status: 403 }))
      if (state === 'replaced') {
        subject.gfsFetch.mockResolvedValueOnce(
          new Response(
            JSON.stringify({
              ok: true,
              data: {
                resourceId: rid,
                rid,
                drive: 'main',
                gfsUri: uri,
                version: 8,
                kind: 'file',
                name: 'neutral.png',
                bytes: replacement.length,
              },
            })
          )
        )
        subject.gfsFetch.mockResolvedValueOnce(
          new Response(new Uint8Array(replacement), {
            headers: {
              'x-gfs-uri': uri,
              'x-gfs-version': '8',
              'content-length': String(replacement.length),
            },
          })
        )
      }
      const reread = await subject.tool.execute(
        { drive: 'main', resourceId: rid },
        {
          onOutput: () => {},
          timeoutMs: 10000,
          visualInput: {
            budget: subject.budget,
            resolveCapability: signal => subject.adapter.getImageInputCapability(signal),
          },
        }
      )
      restored.context_snapshot.push({
        role: 'assistant',
        content: '',
        tool_calls: [
          {
            id: 'explicit-reread',
            name: 'clerum__gfs_read',
            arguments: { drive: 'main', resourceId: rid },
          },
        ],
      })
      appendToolResults(
        restored.context_snapshot,
        [{ ...reread, name: 'clerum__gfs_read', tool_call_id: 'explicit-reread' }],
        []
      )
      const images = restored.context_snapshot
        .flatMap(message => message.contentParts ?? [])
        .filter(part => part.type === 'image')
      if (state === 'revoked') {
        expect(reread.is_error).toBe(true)
        expect(images).toHaveLength(0)
        expect(subject.gfsFetch).toHaveBeenCalledTimes(3)
      } else {
        expect(reread.is_error).toBe(false)
        expect(images).toHaveLength(1)
        expect(images[0].source?.kind === 'gfs' ? images[0].source.version : undefined).toBe(
          state === 'replaced' ? 8 : 7
        )
        expect(images[0].data).toBe(
          (state === 'replaced' ? replacement : original).toString('base64')
        )
        expect(subject.gfsFetch).toHaveBeenCalledTimes(4)
      }
      expect(restored.tool_call_id).toBe('pending-action')
      expect(restored.parameters).toEqual({ command: 'echo done' })
      subject.budget.close()
    }
  )
  it('does not silently lose an image when a shaper changes its message role', async () => {
    const subject = await setup(createCanvas(1, 1).toBuffer('image/png'))
    const shaped = subject.messages.map(message =>
      message.contentParts?.some(p => p.type === 'image')
        ? { ...message, role: 'system' as const }
        : message
    )
    await subject.adapter.completeWithTools({ messages: shaped, tools: [] })
    expect(sdkCreate).toHaveBeenCalledTimes(1)
    expect(JSON.stringify(sdkCreate.mock.calls[0][0])).not.toContain('image_url')
    subject.budget.close()
  })
  it('keeps the destination gate after shaping removes optional image provenance fields', async () => {
    const transport = codexFixture()
    const subject = await setup(createCanvas(1, 1).toBuffer('image/png'), {
      llm: transport.llm,
      catalogState: 'codex-present',
    })
    const shaped = subject.messages.map(message => ({
      ...message,
      contentParts: message.contentParts?.map(part =>
        part.type === 'image'
          ? { type: 'image' as const, mimeType: part.mimeType, data: part.data }
          : part
      ),
    }))
    const completeSingleTurnWithTools = vi.fn().mockResolvedValue({
      content: 'degraded',
      tool_calls: [],
      usage: { input_tokens: 1, output_tokens: 1, total_tokens: 2 },
      finish_reason: 'stop',
    })
    const fallback = new LlmPortAdapter(
      {
        completeSingleTurn: vi.fn(),
        completeSingleTurnWithTools,
        getProviderType: () => 'openai' as const,
        classifyError: vi.fn(),
      },
      'unknown-model',
      'openai',
      undefined,
      undefined,
      undefined,
      undefined,
      undefined
    )
    const fallbackMessages = structuredClone(shaped)
    await fallback.completeWithTools({ messages: fallbackMessages, tools: [] })
    expect(completeSingleTurnWithTools).toHaveBeenCalledTimes(1)
    expect(fallbackMessages.some(m => m.contentParts?.some(p => p.type === 'image'))).toBe(true)
    expect(JSON.stringify(completeSingleTurnWithTools.mock.calls[0][0])).not.toContain(
      '"type":"image"'
    )
    expect(sdkCreate).not.toHaveBeenCalled()
    // The source-binding Codex transport cannot accept pixels whose source was removed.
    await expect(
      subject.adapter.completeWithTools({ messages: shaped, tools: [] })
    ).rejects.toBeDefined()
    expect(transport.stream).not.toHaveBeenCalled()
    subject.budget.close()
  })
  it.each(['image/png', 'image/jpeg'] as const)(
    'preserves unchanged %s bytes through the validated Codex wire',
    async mime => {
      const canvas = createCanvas(8, 8)
      const context = canvas.getContext('2d')
      context.fillStyle = '#186bcc'
      context.fillRect(0, 0, 8, 8)
      const bytes =
        mime === 'image/png' ? canvas.toBuffer('image/png') : canvas.toBuffer('image/jpeg')
      const transport = codexFixture()
      const subject = await setup(bytes, {
        name: 'incorrect-extension.txt',
        llm: transport.llm,
        catalogState: 'codex-present',
      })
      expect(subject.output.is_error).toBe(false)
      expect(subject.output.attachments?.[0].visualSource).toMatchObject({
        gfsUri: uri,
        version: 7,
      })
      expect(subject.collected).toEqual([])
      await subject.adapter.completeWithTools({ messages: subject.messages, tools: [] })
      const request = transport.authorize.mock.calls[0]![0].request as {
        messages: Array<{
          role: string
          content: string
          contentParts?: Array<{ type: string; data?: string }>
        }>
      }
      const imagePart = request.messages
        .flatMap(m => m.contentParts ?? [])
        .find(part => part.type === 'image')
      expect(imagePart!.data).toBe(bytes.toString('base64'))
      const toolMessage = request.messages.find((m: { role: string }) => m.role === 'tool')
      expect(typeof toolMessage!.content).toBe('string')
      expect(toolMessage!.content).not.toContain(bytes.toString('base64'))
      expect(subject.metadataFetch).not.toHaveBeenCalled()
      expect(subject.gfsFetch).toHaveBeenCalledTimes(2)
      subject.budget.close()
      expect(subject.budget.residentBytes).toBe(0)
    }
  )

  it.each([
    '',
    '\ufeffBOM and acentos: áéíóú',
    'tabs\tLF\nCRLF\r\n',
    '{"ok":false,"data":"text"}',
    'PK is a text prefix. RIFF is also a word. Unicode: 🌴\r\n',
  ])('keeps UTF-8 text usable without requiring vision: %j', async text => {
    const subject = await setup(Buffer.from(text), { name: 'note.txt', catalogState: 'missing' })
    expect(subject.output.content).toBe(text.replace(/^\ufeff/, ''))
    expect(subject.output.attachments).toBeUndefined()
    await subject.adapter.completeWithTools({ messages: subject.messages, tools: [] })
    expect(subject.metadataFetch).not.toHaveBeenCalled()
    expect(sdkCreate).toHaveBeenCalledTimes(1)
    subject.budget.close()
  })

  it.each([
    Buffer.from('a\0b'),
    Buffer.from([0xc3, 0x28]),
    Buffer.from([0x01, 0x41]),
    Buffer.from('%PDF-1.7'),
    Buffer.from([0x50, 0x4b, 0x03, 0x04]),
    Buffer.from('<?xml version="1.0"?><svg xmlns="http://www.w3.org/2000/svg"/>'),
    Buffer.from('<svg/>'),
  ])('returns a reference instead of interpreting unsupported bytes as text', async bytes => {
    const subject = await setup(bytes, { name: 'misleading.txt' })
    expect(JSON.parse(subject.output.content).delivery).toBe('reference_only')
    expect(subject.output.attachments).toBeUndefined()
    expect(subject.metadataFetch).not.toHaveBeenCalled()
    subject.budget.close()
  })

  it.each([
    { catalogState: 'unsupported' },
    { catalogState: 'unknown' },
    { catalogState: 'missing' },
  ] as const)(
    'returns an explicit reference when catalog image capability is not established: %j',
    async options => {
      const subject = await setup(createCanvas(1, 1).toBuffer('image/png'), options)
      expect(JSON.parse(subject.output.content).delivery).toBe('reference_only')
      expect(subject.output.attachments).toBeUndefined()
      expect(subject.messages.some(m => m.contentParts?.some(p => p.type === 'image'))).toBe(false)
      subject.budget.close()
    }
  )

  it('rechecks the actual destination instead of forwarding images to an unknown fallback', async () => {
    const transport = codexFixture()
    const subject = await setup(createCanvas(1, 1).toBuffer('image/png'), {
      llm: transport.llm,
      catalogState: 'codex-present',
    })
    const completeSingleTurnWithTools = vi.fn().mockResolvedValue({
      content: 'degraded',
      tool_calls: [],
      usage: { input_tokens: 1, output_tokens: 1, total_tokens: 2 },
      finish_reason: 'stop',
    })
    const fallback = new LlmPortAdapter(
      {
        completeSingleTurn: vi.fn(),
        completeSingleTurnWithTools,
        getProviderType: () => 'openai' as const,
        classifyError: vi.fn(),
      },
      'unknown-model',
      'openai'
    )
    const fallbackMessages = structuredClone(subject.messages)
    await fallback.completeWithTools({ messages: fallbackMessages, tools: [] })
    expect(completeSingleTurnWithTools).toHaveBeenCalledTimes(1)
    expect(fallbackMessages.some(m => m.contentParts?.some(p => p.type === 'image'))).toBe(true)
    expect(JSON.stringify(completeSingleTurnWithTools.mock.calls[0][0])).not.toContain(
      '"type":"image"'
    )
    expect(sdkCreate).not.toHaveBeenCalled()
    subject.budget.close()
  })
})