Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* #666 — `clerum__gfs_read` with `expectedVersion`. The tool runs over the real
* `readGfsContent` behind an HTTP double, so the version decision is the one
* production makes.
*/
import { describe, expect, it, vi } from 'vitest'
import { type GfscReadClient, type ReferencedFilePins, buildGfsReadTools } from './gfs'
import { readGfsContent } from './gfsContentRead'
const FILE_ID = '1234567890abcdef1234567890abcdef'
const FILE_URI = `gfs://main/${FILE_ID}`
const SENTINEL = 'SENTINEL-666-gfs-read-version'
function harness(
snapshotVersion: number,
contentVersion = snapshotVersion,
referencedFiles: ReferencedFilePins = new Map(),
contentUri = FILE_URI
) {
const bytes = Buffer.from(SENTINEL)
const request = vi.fn(async (path: string, _init: RequestInit, _deadlineMs: number) => {
if (!path.includes('/content?'))
return new Response(
JSON.stringify({
ok: true,
data: {
resourceId: FILE_ID,
rid: FILE_ID,
drive: 'main',
gfsUri: FILE_URI,
kind: 'file',
name: 'notes.txt',
version: snapshotVersion,
bytes: bytes.length,
},
})
)
return new Response(new Uint8Array(bytes), {
headers: { 'x-gfs-uri': contentUri, 'x-gfs-version': String(contentVersion) },
})
})
const read = vi.fn<GfscReadClient['read']>((args, options) =>
readGfsContent(request, args, options ?? {})
)
const client: GfscReadClient = {
accessible: vi.fn(),
list: vi.fn(),
read,
stat: vi.fn(),
resolve: vi.fn(),
}
const tool = buildGfsReadTools(client, { referencedFiles }).find(
t => t.name === 'clerum__gfs_read'
)!
const contentRequests = () =>
request.mock.calls.filter(([path]) => path.includes('/content?')).length
return { client, referencedFiles, tool, read, request, contentRequests }
}
describe('clerum__gfs_read expectedVersion (#666)', () => {
it('declares expectedVersion as an optional non-negative integer', () => {
const { tool } = harness(3)
expect(tool.parameters).toMatchObject({
required: ['drive', 'resourceId'],
properties: { expectedVersion: { type: 'integer', minimum: 0 } },
})
})
it('reads the file when it is still at the expected version', async () => {
const { tool, read, contentRequests } = harness(3)
const result = await tool.execute(
{ drive: 'main', resourceId: FILE_ID, expectedVersion: 3 },
''
)
expect(result).toMatchObject({ success: true, content: SENTINEL })
expect(read.mock.calls[0]![0]).toEqual({ drive: 'main', resourceId: FILE_ID })
expect(read.mock.calls[0]![1]).toMatchObject({ expectedVersion: 3 })
expect(contentRequests()).toBe(1)
})
it('answers a typed stale result without content when the file changed', async () => {
const { tool, request, contentRequests } = harness(4)
const result = await tool.execute(
{ drive: 'main', resourceId: FILE_ID, expectedVersion: 3 },
''
)
expect(result.success).toBe(true)
expect(JSON.parse(result.content as string)).toEqual({
availability: 'stale',
drive: 'main',
resourceId: FILE_ID,
expectedVersion: 3,
})
// Witness: the metadata snapshot was requested; the content never was.
expect(request).toHaveBeenCalledTimes(1)
expect(contentRequests()).toBe(0)
expect(result.content).not.toContain(SENTINEL)
})
it('answers stale when the content version moves during an expected-version read', async () => {
const { tool, contentRequests } = harness(3, 4)
const result = await tool.execute(
{ drive: 'main', resourceId: FILE_ID, expectedVersion: 3 },
''
)
// Witness: the content request was made, and its header decided the answer.
expect(contentRequests()).toBe(1)
expect(JSON.parse(result.content as string)).toMatchObject({ availability: 'stale' })
})
it('keeps the failed result for a version conflict when no version was expected', async () => {
const { tool, read, contentRequests } = harness(3, 4)
const result = await tool.execute({ drive: 'main', resourceId: FILE_ID }, '')
expect(contentRequests()).toBe(1)
expect(result).toEqual({ success: false, error: 'GFS read failed (version_conflict)' })
expect(read.mock.calls[0]![1]).not.toHaveProperty('expectedVersion')
})
it.each([-1, 1.5, '3', null])('rejects expectedVersion %j before reading', async value => {
const { tool, read } = harness(3)
// Control: a valid expectedVersion reaches the client.
await tool.execute({ drive: 'main', resourceId: FILE_ID, expectedVersion: 3 }, '')
expect(read).toHaveBeenCalledTimes(1)
const result = await tool.execute(
{ drive: 'main', resourceId: FILE_ID, expectedVersion: value },
''
)
expect(result).toEqual({
success: false,
error: 'expectedVersion must be a non-negative integer.',
})
expect(read).toHaveBeenCalledTimes(1)
})
it('answers identity_mismatch, not stale, when the content names another resource', async () => {
const { tool, contentRequests } = harness(3, 3, new Map(), `gfs://main/${'f'.repeat(32)}`)
const result = await tool.execute(
{ drive: 'main', resourceId: FILE_ID, expectedVersion: 3 },
''
)
// Witness: the content request was made, and its header decided the answer.
expect(contentRequests()).toBe(1)
expect(result).toEqual({ success: false, error: 'GFS read failed (identity_mismatch)' })
})
})
describe('live-resource descriptions (#666)', () => {
it('list, stat and resolve each say they report the live version', () => {
const client: GfscReadClient = {
accessible: vi.fn(),
list: vi.fn(),
read: vi.fn(),
stat: vi.fn(),
resolve: vi.fn(),
}
const tools = buildGfsReadTools(client, { referencedFiles: new Map() })
const note =
'Reports the live resource; a file referenced in the current message is read at its listed version, or at its current_version once the reference is stale.'
for (const name of ['clerum__gfs_list', 'clerum__gfs_stat', 'clerum__gfs_resolve']) {
const tool = tools.find(tool => tool.name === name)
expect(tool?.description).toContain(note)
}
// Witness: the note belongs to the live-version tools, not to gfs_read.
const read = tools.find(tool => tool.name === 'clerum__gfs_read')
expect(read?.description).not.toContain('Reports the live resource')
})
})
describe('clerum__gfs_read pinned by a file reference of the message (#666)', () => {
const pinned = (version: number, currentVersion?: number): ReferencedFilePins =>
new Map([
[`main/${FILE_ID}`, { version, ...(currentVersion === undefined ? {} : { currentVersion }) }],
])
it('reads the referenced version when the model omits expectedVersion', async () => {
const { tool, read, contentRequests } = harness(3, 3, pinned(3))
const result = await tool.execute({ drive: 'main', resourceId: FILE_ID }, '')
expect(result).toMatchObject({ success: true, content: SENTINEL })
expect(read).toHaveBeenCalledTimes(1)
expect(read.mock.calls[0]![1]).toMatchObject({ expectedVersion: 3 })
expect(contentRequests()).toBe(1)
})
it('reads the referenced version when the model passes it', async () => {
const { tool, read } = harness(3, 3, pinned(3))
const result = await tool.execute(
{ drive: 'main', resourceId: FILE_ID, expectedVersion: 3 },
''
)
expect(result).toMatchObject({ success: true, content: SENTINEL })
expect(read.mock.calls[0]![1]).toMatchObject({ expectedVersion: 3 })
})
it('matches the pin for a dashed, upper-case resourceId', async () => {
const { tool, read } = harness(3, 3, pinned(3))
const dashed = `${FILE_ID.slice(0, 8)}-${FILE_ID.slice(8)}`.toUpperCase()
await tool.execute({ drive: 'main', resourceId: dashed }, '')
expect(read).toHaveBeenCalledTimes(1)
expect(read.mock.calls[0]![1]).toMatchObject({ expectedVersion: 3 })
})
it('reads the current_version of a stale reference when the model passes it', async () => {
const { tool, read, contentRequests } = harness(4, 4, pinned(3, 4))
const result = await tool.execute(
{ drive: 'main', resourceId: FILE_ID, expectedVersion: 4 },
''
)
expect(result).toMatchObject({ success: true, content: SENTINEL })
expect(read.mock.calls[0]![1]).toMatchObject({ expectedVersion: 4 })
expect(contentRequests()).toBe(1)
})
it('answers stale for a stale reference read without expectedVersion', async () => {
const { tool, read, contentRequests } = harness(4, 4, pinned(3, 4))
const result = await tool.execute({ drive: 'main', resourceId: FILE_ID }, '')
// Witness: the read ran at the referenced version and the snapshot decided.
expect(read.mock.calls[0]![1]).toMatchObject({ expectedVersion: 3 })
expect(JSON.parse(result.content as string)).toEqual({
availability: 'stale',
drive: 'main',
resourceId: FILE_ID,
expectedVersion: 3,
})
expect(contentRequests()).toBe(0)
})
it('refuses any other version without reading, naming the referenced version', async () => {
const { tool, read } = harness(3, 3, pinned(3))
const result = await tool.execute(
{ drive: 'main', resourceId: FILE_ID, expectedVersion: 5 },
''
)
expect(result).toEqual({
success: false,
error:
'This file is referenced in the current message at version 3. Omit expectedVersion or pass 3.',
})
expect(read).not.toHaveBeenCalled()
})
it('refuses any other version of a stale reference, naming both versions', async () => {
const { tool, read } = harness(4, 4, pinned(3, 4))
const result = await tool.execute(
{ drive: 'main', resourceId: FILE_ID, expectedVersion: 2 },
''
)
expect(result).toEqual({
success: false,
error:
'This file is referenced in the current message at version 3. Omit expectedVersion or pass 3, or pass its current_version 4 to read the current file.',
})
expect(read).not.toHaveBeenCalled()
})
it('lets stat report a newer live version and still reads the referenced one', async () => {
const { client, referencedFiles, tool, read } = harness(3, 3, pinned(3))
vi.mocked(client.stat).mockResolvedValue({
resourceId: FILE_ID,
drive: 'main',
gfsUri: FILE_URI,
kind: 'file',
name: 'notes.txt',
version: 4,
bytes: SENTINEL.length,
} as Awaited<ReturnType<GfscReadClient['stat']>>)
const stat = buildGfsReadTools(client, { referencedFiles }).find(
t => t.name === 'clerum__gfs_stat'
)!
const statResult = await stat.execute({ drive: 'main', resourceId: FILE_ID }, '')
expect(client.stat).toHaveBeenCalledTimes(1)
expect(JSON.parse(statResult.content as string)).toMatchObject({ version: 4 })
// Witness that stat left the pin intact: the read still asks for version 3.
await tool.execute({ drive: 'main', resourceId: FILE_ID }, '')
expect(read).toHaveBeenCalledTimes(1)
expect(read.mock.calls[0]![1]).toMatchObject({ expectedVersion: 3 })
})
it('leaves a file the message did not reference unpinned', async () => {
const other = new Map([[`main/${'e'.repeat(32)}`, { version: 9 }]])
const { tool, read } = harness(3, 3, other)
const result = await tool.execute({ drive: 'main', resourceId: FILE_ID }, '')
expect(result).toMatchObject({ success: true, content: SENTINEL })
expect(read).toHaveBeenCalledTimes(1)
expect(read.mock.calls[0]![1]).not.toHaveProperty('expectedVersion')
})
})