Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { describe, expect, it, vi } from 'vitest'
import { createHash, randomUUID } from 'node:crypto'
import { createRequire } from 'node:module'
import { join } from 'node:path'
import { crc32, deflateSync } from 'node:zlib'
import { JPEG_2X2_BASE64, PNG_2X2_BASE64 } from '../llm/__tests__/codexImageFixtures'
import { resolveVisualDeliveryLimits } from '../visualInput/deliveryLimits'
import { VisualInputBudget } from '../visualInput/policy'
import { type GfscReadClient, buildGfsReadTools } from './gfs'
import {
type GfsDownloadStore,
GfsDownloadStoreError,
type GfsDownloadStoreErrorCode,
} from './gfsDownloadStore'
import { GFS_CACHE_FULL_GUIDANCE, GFS_DISK_FULL_GUIDANCE } from './gfsSpaceGuidance'
const MIB = 1024 * 1024
const target = { drive: 'main', resourceId: 'a'.repeat(32) }
const source = {
kind: 'gfs' as const,
...target,
version: 7,
gfsUri: `gfs://main/${target.resourceId}`,
name: 'image-without-extension',
}
const { realPngOfSize, padJpegToSize } = createRequire(join(__dirname, 'gfsManagedImage.test.ts'))(
'../../../packages/llm-provider-attempt-contract/testImageFixtures.cjs'
) as {
realPngOfSize: (size: number, width: number, height: number, seed: number) => Buffer
padJpegToSize: (bytes: Buffer, size: number) => Buffer
}
const largePng = realPngOfSize(3 * MIB + 1, 2, 2, 7)
const largeJpeg = padJpegToSize(Buffer.from(JPEG_2X2_BASE64, 'base64'), 3 * MIB + 1)
const smallPng = Buffer.from(PNG_2X2_BASE64, 'base64')
/**
* Keep the byte-boundary fixture decoder-cheap. A single multi-MiB tEXt chunk
* can exhaust the native decoder's five-second limit on Linux; small ancillary
* chunks preserve the exact source size and independently decoded 2x2 raster.
*/
function pngWithBoundedTextChunks(size: number): Buffer {
const maxChunkBytes = 512 * 1024
let remaining = size - smallPng.byteLength
const chunks: Buffer[] = [smallPng.subarray(0, smallPng.byteLength - 12)]
while (remaining > 0) {
let chunkBytes = Math.min(remaining, maxChunkBytes)
if (remaining > chunkBytes && remaining - chunkBytes < 16) chunkBytes -= 16
if (chunkBytes < 16) throw new Error('PNG fixture needs space for a complete tEXt chunk')
const type = Buffer.from('tEXt', 'ascii')
const data = Buffer.alloc(chunkBytes - 12, 0x20)
Buffer.from('pad\0', 'latin1').copy(data)
const length = Buffer.alloc(4)
length.writeUInt32BE(data.byteLength)
const checksum = Buffer.alloc(4)
checksum.writeUInt32BE(crc32(Buffer.concat([type, data])))
chunks.push(Buffer.concat([length, type, data, checksum]))
remaining -= chunkBytes
}
chunks.push(smallPng.subarray(smallPng.byteLength - 12))
const png = Buffer.concat(chunks)
if (png.byteLength !== size) throw new Error('PNG fixture source size mismatch')
return png
}
/** A valid one-bit grayscale PNG whose real decoder verifies the raster. */
function compressed2048Png(): Buffer {
const chunk = (name: string, data: Buffer): Buffer => {
const type = Buffer.from(name, 'ascii')
const length = Buffer.alloc(4)
length.writeUInt32BE(data.byteLength)
const checksum = Buffer.alloc(4)
checksum.writeUInt32BE(crc32(Buffer.concat([type, data])))
return Buffer.concat([length, type, data, checksum])
}
const header = Buffer.alloc(13)
header.writeUInt32BE(2048, 0)
header.writeUInt32BE(2048, 4)
header[8] = 1
header[9] = 0
const raster = Buffer.alloc((1 + 2048 / 8) * 2048)
return Buffer.concat([
Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
chunk('IHDR', header),
chunk('IDAT', deflateSync(raster, { level: 9 })),
chunk('IEND', Buffer.alloc(0)),
])
}
function scenario(
bytes: Buffer,
options: {
budget?: VisualInputBudget
provider?: string
signal?: AbortSignal
declaredSize?: number
readManaged?: () => Promise<Buffer>
} = {}
) {
const retentionOwnerId = randomUUID()
const budget = options.budget ?? new VisualInputBudget()
const receipt = {
id: 'managed-image',
source,
path: '.gfs-downloads/managed-image/source',
sizeBytes: options.declaredSize ?? bytes.byteLength,
sha256: createHash('sha256').update(bytes).digest('hex'),
expiresAt: new Date(Date.now() + 60_000).toISOString(),
}
const store = {
readManagedFilePrefix: vi.fn(async () => bytes.subarray(0, 16)),
readManagedFile: vi.fn(options.readManaged ?? (async () => bytes)),
}
const client = {
accessible: vi.fn(),
list: vi.fn(),
stat: vi.fn(),
resolve: vi.fn(),
readMetadata: vi.fn(async () => ({ source, size: receipt.sizeBytes })),
download: vi.fn<NonNullable<GfscReadClient['download']>>(async (_target, options) => {
expect(options.retentionOwnerId).toBe(retentionOwnerId)
return receipt
}),
read: vi.fn(async () => {
const reservation = budget.reserve(bytes.byteLength)
budget.consumeRead(bytes.byteLength)
return { source, bytes, reservation }
}),
} satisfies GfscReadClient
const capability = vi.fn(async () => ({
status: 'supported' as const,
provider: options.provider ?? 'codex-subscription',
deliveryLimits: resolveVisualDeliveryLimits(options.provider ?? 'codex-subscription'),
model: 'fixture-model',
evidence: 'fixture-catalog',
}))
const tool = buildGfsReadTools(client, {
referencedFiles: new Map(),
downloadStore: store as unknown as GfsDownloadStore,
callerIdentity: 'caller-a',
callerWorkspacePath: '/tmp/managed-image-caller',
retentionOwnerId,
}).find(item => item.name === 'clerum__gfs_read')!
return {
budget,
store,
client,
receipt,
capability,
run: () =>
tool.execute(target, '/tmp', {
signal: options.signal,
visualInput: { budget, resolveCapability: capability },
}),
}
}
describe('GFS managed image projection', () => {
it.each([
['PNG', largePng],
['JPEG', largeJpeg],
])(
'delivers a decoded valid %s beyond 3 MiB under the effective Codex profile',
async (_format, bytes) => {
const subject = scenario(bytes)
const result = await subject.run()
expect(result.success).toBe(true)
expect(JSON.parse(result.content!).visualReason).toBeUndefined()
expect(JSON.parse(result.content!)).toMatchObject({
...subject.receipt,
delivery: 'workspace_file',
visualDelivery: 'included',
usage: { visualDelivery: 'included', wholeFileToContextAllowed: false },
})
expect(result.images).toHaveLength(1)
expect(
createHash('sha256')
.update(Buffer.from(result.images![0]!.dataBase64, 'base64'))
.digest('hex')
).toBe(subject.receipt.sha256)
expect(subject.client.read).not.toHaveBeenCalled()
expect(subject.store.readManagedFile).toHaveBeenCalledOnce()
expect(subject.budget.readBytes).toBe(bytes.byteLength)
expect(subject.budget.residentBytes).toBe(4 * Math.ceil(bytes.byteLength / 3) * 2)
}
)
it.each([8 * MIB, 16 * MIB])(
'accepts %i source bytes through the Codex visual boundary',
async size => {
const png = pngWithBoundedTextChunks(size)
expect(png.byteLength).toBe(size)
const subject = scenario(png)
const result = await subject.run()
expect(result.success).toBe(true)
const receipt = JSON.parse(result.content!)
expect(
receipt.visualReason,
JSON.stringify({
sizeBytes: size,
visualReason: receipt.visualReason ?? null,
imageCount: result.images?.length ?? 0,
readBytes: subject.budget.readBytes,
residentBytes: subject.budget.residentBytes,
})
).toBeUndefined()
expect(receipt).toMatchObject({
sizeBytes: size,
visualDelivery: 'included',
usage: { visualDelivery: 'included' },
})
expect(result.images![0]!.sizeBytes).toBe(size)
expect(
createHash('sha256')
.update(Buffer.from(result.images![0]!.dataBase64, 'base64'))
.digest('hex')
).toBe(subject.receipt.sha256)
expect(subject.budget.readBytes).toBe(size)
expect(subject.budget.residentBytes).toBe(4 * Math.ceil(size / 3) * 2)
},
// Fixture construction, two framing passes and proof hashing surround the
// decoder's independent 5-second runtime deadline; they need their own time.
15_000
)
it('accepts a real 2048-square PNG without double-charging inline classification', async () => {
const png = compressed2048Png()
expect(png.byteLength).toBeLessThanOrEqual(8192)
const subject = scenario(png)
const result = await subject.run()
expect(result.success).toBe(true)
expect(result.images).toMatchObject([{ width: 2048, height: 2048 }])
expect(subject.client.read).toHaveBeenCalledOnce()
expect(subject.store.readManagedFile).not.toHaveBeenCalled()
expect(subject.budget.readBytes).toBe(png.byteLength)
expect(subject.budget.residentBytes).toBe(4 * Math.ceil(png.byteLength / 3) * 2)
})
it('reserves and charges raw bytes before starting the managed-file read', async () => {
const budget = new VisualInputBudget()
const subject = scenario(largePng, {
budget,
readManaged: async () => {
expect(budget.residentBytes).toBe(largePng.byteLength)
expect(budget.readBytes).toBe(largePng.byteLength)
return largePng
},
})
expect((await subject.run()).success).toBe(true)
})
it('preserves an admitted source above the visual profile without loading its body', async () => {
// The injected GFSC client represents a deployment with raised source
// admission; this test targets projection rather than metadata admission.
const subject = scenario(smallPng, { declaredSize: 16 * MIB + 1 })
const result = await subject.run()
expect(JSON.parse(result.content!)).toMatchObject({
...subject.receipt,
visualDelivery: 'not_included',
visualReason: 'provider_visual_limit_exceeded',
usage: { visualDelivery: 'not_included' },
})
expect(result.images).toBeUndefined()
expect(subject.store.readManagedFile).not.toHaveBeenCalled()
expect(subject.budget.readBytes).toBe(0)
expect(subject.budget.residentBytes).toBe(0)
})
it('keeps an unmeasured provider receipt without applying the legacy 3 MiB profile', async () => {
const subject = scenario(largePng, { provider: 'openai' })
const result = await subject.run()
expect(JSON.parse(result.content!)).toMatchObject({
...subject.receipt,
visualReason: 'provider_visual_profile_unavailable',
visualDelivery: 'not_included',
})
expect(subject.store.readManagedFile).not.toHaveBeenCalled()
expect(subject.budget.residentBytes).toBe(0)
expect(result.images).toBeUndefined()
})
it.each([
['resident', () => new VisualInputBudget(largePng.byteLength - 1)],
['read', () => new VisualInputBudget(96 * MIB, largePng.byteLength - 1)],
[
'closed',
() => {
const budget = new VisualInputBudget()
budget.close()
return budget
},
],
])('rejects an insufficient %s budget before loading the source', async (_kind, makeBudget) => {
const subject = scenario(largePng, { budget: makeBudget() })
const result = await subject.run()
expect(JSON.parse(result.content!)).toMatchObject({
...subject.receipt,
visualDelivery: 'not_included',
visualReason: 'local_visual_resources_exceeded',
})
expect(subject.store.readManagedFile).not.toHaveBeenCalled()
expect(subject.budget.residentBytes).toBe(0)
expect(result.images).toBeUndefined()
})
it('releases its raw reservation when cancellation arrives during the read', async () => {
const controller = new AbortController()
const subject = scenario(largePng, {
signal: controller.signal,
readManaged: async () => {
controller.abort()
return largePng
},
})
const result = await subject.run()
expect(result.success).toBe(false)
expect(result.error).toContain('cancelled')
expect(result.images).toBeUndefined()
expect(subject.budget.residentBytes).toBe(0)
expect(subject.budget.readBytes).toBe(largePng.byteLength)
})
it('does not expose a receipt as usable when the retained file fails integrity', async () => {
const subject = scenario(largePng, {
readManaged: async () => {
throw new GfsDownloadStoreError('download_missing')
},
})
const result = await subject.run()
expect(result.success).toBe(false)
expect(result.error).toContain('download_missing')
expect(result.content).toBeUndefined()
expect(subject.budget.residentBytes).toBe(0)
})
})
describe('GFS download store errors at the tool boundary', () => {
const codes: GfsDownloadStoreErrorCode[] = [
'caller_mismatch',
'disk_full',
'download_busy',
'download_expired',
'download_missing',
'host_quota_exceeded',
'limit_exceeded',
'publication_cancelled',
'storage_write_failed',
'volume_unmeasurable',
'workspace_unavailable',
]
// Only the two space refusals carry guidance, as an exact second line; an
// unmeasurable volume is the bare envelope.
const toolError = (code: GfsDownloadStoreErrorCode): string =>
code === 'disk_full'
? `GFS download store failed (disk_full)\n${GFS_DISK_FULL_GUIDANCE}`
: code === 'host_quota_exceeded'
? `GFS download store failed (host_quota_exceeded)\n${GFS_CACHE_FULL_GUIDANCE}`
: `GFS download store failed (${code})`
it.each(codes)('surfaces store code %s to the model', async code => {
const subject = scenario(largePng, {
readManaged: async () => {
throw new GfsDownloadStoreError(code)
},
})
const result = await subject.run()
expect(subject.store.readManagedFile).toHaveBeenCalledTimes(1)
expect(result.success).toBe(false)
expect(result.error).toBe(toolError(code))
expect(subject.budget.residentBytes).toBe(0)
})
it.each(codes)('surfaces download admission code %s to the model', async code => {
const subject = scenario(largePng)
subject.client.download.mockImplementation(async () => {
throw new GfsDownloadStoreError(code)
})
const result = await subject.run()
expect(subject.client.download).toHaveBeenCalledTimes(1)
expect(subject.store.readManagedFile).not.toHaveBeenCalled()
expect(result.success).toBe(false)
expect(result.error).toBe(toolError(code))
})
})