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 { createCanvas } from '@napi-rs/canvas'
import { resolveOfficialVisualDeliveryLimits } from '../visualInput/deliveryLimits'
import { VisualInputBudget } from '../visualInput/policy'
import {
type GfscReadClient,
type GfscWriteClient,
buildGfsCopyTools,
buildGfsReadTools,
buildGfsWriteTools,
} from './gfs'
import { GfscHttpError } from './gfsClient'
/**
* P3-S04 — agent gfs READ tools. Four read-only tools (list/read/stat/resolve)
* over a gfsc client; results carry gfsUri. No write tool in P3.
*/
function client(overrides?: Partial<GfscReadClient>): GfscReadClient {
return {
accessible: vi.fn(async () => ({
items: [{ gfsUri: 'gfs://main/abc', permissions: ['read', 'write'] }],
})),
list: vi.fn(async () => ({ entries: [{ gfsUri: 'gfs://main/abc' }] })),
read: vi.fn(async () => ({
source: {
kind: 'gfs' as const,
drive: 'main',
resourceId: 'a'.repeat(32),
gfsUri: `gfs://main/${'a'.repeat(32)}`,
version: 2,
name: 'note.txt',
},
bytes: Buffer.from('hi'),
reservation: { release: vi.fn() },
})),
stat: vi.fn(async () => ({ gfsUri: 'gfs://main/abc', kind: 'file', version: 2 })),
resolve: vi.fn(async () => ({ gfsUri: 'gfs://main/abc', pathCache: '/a' })),
...overrides,
}
}
function toolMap(c: GfscReadClient) {
return new Map(buildGfsReadTools(c, { referencedFiles: new Map() }).map(t => [t.name, t]))
}
// A tool run with no caller context passes no cancel signal and no deadline to
// the client, so only the client's maxRetryWaitMs bounds a retry.
const NO_BOUNDS = { signal: undefined, deadlineMs: undefined }
describe('buildGfsReadTools', () => {
it('exposes the read tools plus accessible-resource discovery', () => {
const names = buildGfsReadTools(client(), { referencedFiles: new Map() })
.map(t => t.name)
.sort()
expect(names).toEqual([
'clerum__gfs_accessible',
'clerum__gfs_list',
'clerum__gfs_read',
'clerum__gfs_resolve',
'clerum__gfs_stat',
])
})
it('gfs_accessible returns resources and permissions the agent can use', async () => {
const c = client()
const r = await toolMap(c).get('clerum__gfs_accessible')!.execute({ drive: 'main' }, '')
expect(r.success).toBe(true)
expect(r.content).toContain('gfs://main/abc')
expect(r.content).toContain('write')
expect(c.accessible).toHaveBeenCalledWith({ drive: 'main' }, NO_BOUNDS)
})
it('turns the caller context into the call signal and an absolute deadline', async () => {
const T = 1_900_000_000_000
const now = vi.spyOn(Date, 'now').mockReturnValue(T)
const c = client()
const controller = new AbortController()
const r = await toolMap(c)
.get('clerum__gfs_stat')!
.execute({ drive: 'main', resourceId: 'abc' }, '', {
signal: controller.signal,
timeoutMs: 5000,
})
now.mockRestore()
expect(r.success).toBe(true)
expect(c.stat).toHaveBeenCalledTimes(1)
const call = vi.mocked(c.stat).mock.calls[0]?.[1]
expect(call).toEqual({ signal: controller.signal, deadlineMs: T + 5000 })
expect(call?.signal).toBe(controller.signal)
})
it('gfs_list returns the gfsc result on success', async () => {
const c = client()
const r = await toolMap(c)
.get('clerum__gfs_list')!
.execute({ drive: 'main', resourceId: 'abc' }, '')
expect(r.success).toBe(true)
expect(r.content).toContain('gfs://main/abc')
expect(c.list).toHaveBeenCalledWith({ drive: 'main', resourceId: 'abc' }, NO_BOUNDS)
})
it('gfs_resolve calls the resolver', async () => {
const c = client()
const r = await toolMap(c).get('clerum__gfs_resolve')!.execute({ uri: 'gfs://main/abc' }, '')
expect(r.success).toBe(true)
expect(c.resolve).toHaveBeenCalledWith({ uri: 'gfs://main/abc' }, NO_BOUNDS)
})
it('surfaces a gfsc error as a redacted failed result (fail-loud, e.g. a revoked grant)', async () => {
const c = client({
read: vi.fn(async () => {
throw new Error('gfsc 403: grant revoked for /internal/server/path with blob blob/key')
}),
})
const r = await toolMap(c)
.get('clerum__gfs_read')!
.execute({ drive: 'main', resourceId: 'abc' }, '')
expect(r.success).toBe(false)
expect(r.error).toBe('GFS read failed (gfsc 403: forbidden)')
expect(r.error).not.toContain('/internal/server/path')
expect(r.error).not.toContain('blob/key')
})
it('returns typed image input when the destination supports vision', async () => {
const canvas = createCanvas(2, 2)
canvas.getContext('2d').fillRect(0, 0, 2, 2)
const bytes = canvas.toBuffer('image/png')
const source = {
kind: 'gfs' as const,
drive: 'main',
resourceId: 'a'.repeat(32),
gfsUri: `gfs://main/${'a'.repeat(32)}`,
version: 2,
name: 'pic.png',
}
const reservation = { release: vi.fn() }
const c = client({
read: vi.fn(async () => ({ source, bytes, reservation })),
})
const r = await toolMap(c)
.get('clerum__gfs_read')!
.execute({ drive: 'main', resourceId: source.resourceId }, '', {
visualInput: {
budget: new VisualInputBudget(),
resolveCapability: async () => ({
status: 'supported',
provider: 'openai',
deliveryLimits: resolveOfficialVisualDeliveryLimits(
'openai',
'https://api.openai.com/v1',
'completeWithTools'
),
model: 'gpt-4.1',
evidence: 'unit',
}),
},
})
expect(r.success).toBe(true)
expect(JSON.parse(r.content as string).delivery).toBe('image_input')
expect(r.images?.[0]).toMatchObject({ mimeType: 'image/png', source })
expect(reservation.release).toHaveBeenCalledOnce()
})
it.each(['<svg/>', '<svg />', '<SVG/>', '\uFEFF<svg/>'])(
'returns a reference for self-closing SVG %j',
async text => {
const c = client({
read: vi.fn(async () => ({
source: {
kind: 'gfs' as const,
drive: 'main',
resourceId: 'a'.repeat(32),
gfsUri: `gfs://main/${'a'.repeat(32)}`,
version: 2,
name: 'icon.svg',
},
bytes: Buffer.from(text),
reservation: { release: vi.fn() },
})),
})
const r = await toolMap(c)
.get('clerum__gfs_read')!
.execute({ drive: 'main', resourceId: 'abc' }, '')
expect(r.success).toBe(true)
expect(JSON.parse(r.content as string)).toMatchObject({
delivery: 'reference_only',
reason: 'svg_visual_input_not_supported',
})
}
)
it('strips a UTF-8 BOM from otherwise valid text', async () => {
const c = client({
read: vi.fn(async () => ({
source: {
kind: 'gfs' as const,
drive: 'main',
resourceId: 'a'.repeat(32),
gfsUri: `gfs://main/${'a'.repeat(32)}`,
version: 2,
name: 'note.txt',
},
bytes: Buffer.from('\uFEFFhello'),
reservation: { release: vi.fn() },
})),
})
const r = await toolMap(c)
.get('clerum__gfs_read')!
.execute({ drive: 'main', resourceId: 'abc' }, '')
expect(r.success).toBe(true)
expect(r.content).toBe('hello')
})
it('passes a 429 retry hint to the model and still redacts the body', async () => {
const c = client({
read: vi.fn(async () => {
throw new GfscHttpError(429, 'rate limited on /internal/server/path blob/key', 30)
}),
})
const r = await toolMap(c)
.get('clerum__gfs_read')!
.execute({ drive: 'main', resourceId: 'abc' }, '')
expect(r.success).toBe(false)
expect(r.error).toBe('GFS read failed (gfsc 429: rate_limited, retry after 30s)')
expect(r.error).not.toContain('/internal/server/path')
expect(r.error).not.toContain('blob/key')
})
it.each([
[429, 'rate_limited'],
[400, 'invalid_request'],
[503, 'unavailable'],
])('maps gfsc %s without a hint to %s', async (status, category) => {
const c = client({
stat: vi.fn(async () => {
throw new GfscHttpError(status, 'private path=/data/gfs/secret')
}),
})
const r = await toolMap(c)
.get('clerum__gfs_stat')!
.execute({ drive: 'main', resourceId: 'abc' }, '')
expect(r).toEqual({ success: false, error: `GFS read failed (gfsc ${status}: ${category})` })
})
it('strips a non-gfsc-shaped read error down to the generic label', async () => {
const c = client({
read: vi.fn(async () => {
throw new Error('connect ECONNREFUSED 10.96.0.7:8087')
}),
})
const r = await toolMap(c)
.get('clerum__gfs_read')!
.execute({ drive: 'main', resourceId: 'abc' }, '')
expect(r.success).toBe(false)
expect(r.error).toBe('GFS read failed')
})
})
describe('buildGfsWriteTools (P4)', () => {
function writeClient(overrides?: Partial<GfscWriteClient>): GfscWriteClient {
return {
list: vi.fn(),
accessible: vi.fn(),
read: vi.fn(),
stat: vi.fn(),
resolve: vi.fn(),
write: vi.fn(async () => ({ gfsUri: 'gfs://main/abc', version: 4 })),
createFile: vi.fn(async () => ({ resourceId: 'file' })),
createFolder: vi.fn(async () => ({ resourceId: 'folder' })),
rename: vi.fn(async () => ({ resourceId: 'abc', version: 5 })),
copy: vi.fn(async () => ({
resourceId: 'copy',
gfsUri: 'gfs://main/copy',
objectCount: 3,
fileCount: 2,
folderCount: 1,
totalBytes: 8,
requestId: 'request-1',
})),
...overrides,
} as GfscWriteClient
}
it('exposes only the narrowly named non-destructive write tools', () => {
expect(buildGfsWriteTools(writeClient()).map(t => t.name)).toEqual([
'clerum__gfs_write',
'clerum__gfs_create_file',
'clerum__gfs_create_folder',
'clerum__gfs_rename',
])
})
it('writes with a numeric If-Match and returns the result', async () => {
const c = writeClient()
const tool = buildGfsWriteTools(c)[0]!
const r = await tool.execute(
{ drive: 'main', resourceId: 'abc', content: 'hi', ifMatch: 3 },
''
)
expect(r.success).toBe(true)
expect(c.write).toHaveBeenCalledWith(
{
drive: 'main',
resourceId: 'abc',
content: 'hi',
ifMatch: 3,
},
NO_BOUNDS
)
})
it('rejects a write without If-Match (agent writes are writer-routed conditional)', async () => {
const c = writeClient()
const tool = buildGfsWriteTools(c)[0]!
const r = await tool.execute({ drive: 'main', resourceId: 'abc', content: 'hi' }, '')
expect(r.success).toBe(false)
expect(r.error).toMatch(/If-Match/i)
expect(c.write).not.toHaveBeenCalled()
})
it.each([
['clerum__gfs_write', { drive: 'main', resourceId: 'abc', content: 'hi' }],
['clerum__gfs_rename', { drive: 'main', resourceId: 'abc', newName: 'renamed.txt' }],
[
'clerum__gfs_copy',
{ drive: 'main', sourceResourceId: 'source', destinationParentId: 'destination' },
],
])('rejects invalid If-Match values before %s reaches gfsc', async (name, baseArgs) => {
for (const ifMatch of [Number.NaN, -1, 1.5, Number.MAX_SAFE_INTEGER + 1]) {
const c = writeClient()
const tools = new Map(
[...buildGfsWriteTools(c), ...buildGfsCopyTools(c)].map(tool => [tool.name, tool])
)
const result = await tools.get(name)!.execute({ ...baseArgs, ifMatch }, '')
expect(result.success).toBe(false)
expect(result.error).toMatch(/non-negative safe-integer If-Match/)
expect(c.write).not.toHaveBeenCalled()
expect(c.rename).not.toHaveBeenCalled()
expect(c.copy).not.toHaveBeenCalled()
}
})
it('passes create and rename payloads without exposing move fields', async () => {
const c = writeClient()
const tools = new Map(buildGfsWriteTools(c).map(tool => [tool.name, tool]))
await tools
.get('clerum__gfs_create_file')!
.execute(
{ drive: 'main', parentResourceId: 'parent', name: 'note.txt', content: 'hello' },
''
)
await tools
.get('clerum__gfs_create_folder')!
.execute({ drive: 'main', parentResourceId: 'parent', name: 'docs' }, '')
await tools
.get('clerum__gfs_rename')!
.execute({ drive: 'main', resourceId: 'abc', newName: 'renamed.txt', ifMatch: 4 }, '')
expect(c.createFile).toHaveBeenCalledWith(
{
drive: 'main',
parentResourceId: 'parent',
name: 'note.txt',
content: 'hello',
},
NO_BOUNDS
)
expect(c.createFolder).toHaveBeenCalledWith(
{
drive: 'main',
parentResourceId: 'parent',
name: 'docs',
},
NO_BOUNDS
)
expect(c.rename).toHaveBeenCalledWith(
{
drive: 'main',
resourceId: 'abc',
newName: 'renamed.txt',
ifMatch: 4,
},
NO_BOUNDS
)
expect(tools.has('clerum__gfs_move')).toBe(false)
expect(tools.has('clerum__gfs_delete')).toBe(false)
})
it('copies through one server-side call with the exact root contract', async () => {
const c = writeClient()
const tool = buildGfsCopyTools(c)[0]!
expect(tool.description).toContain('The original remains at the source')
expect(tool.description).toContain('never deletes it')
const args = {
drive: 'main',
sourceResourceId: 'source',
destinationParentId: 'destination',
newName: 'source-copy',
ifMatch: 7,
}
const result = await tool.execute(args, '')
expect(result.success).toBe(true)
expect(c.copy).toHaveBeenCalledTimes(1)
expect(c.copy).toHaveBeenCalledWith(args, NO_BOUNDS)
expect(c.read).not.toHaveBeenCalled()
expect(c.write).not.toHaveBeenCalled()
})
it('does not expose backend paths or keys in mutation failures', async () => {
const c = writeClient({
copy: vi.fn(async () => {
throw new Error('failed at /mnt/gfs/private/blob-key')
}),
})
const result = await buildGfsCopyTools(c)[0]!.execute(
{ drive: 'main', sourceResourceId: 'source', destinationParentId: 'destination', ifMatch: 7 },
''
)
expect(result).toEqual({ success: false, error: 'GFS mutation failed' })
})
it.each([
[403, 'forbidden'],
[409, 'conflict'],
[412, 'precondition_failed'],
[413, 'limit_exceeded'],
[503, 'unavailable'],
])('preserves safe gfsc status/category for mutation failure %s', async (status, category) => {
const c = writeClient({
copy: vi.fn(async () => {
throw new Error(
`gfsc ${status}: private path=/data/gfs/.generations/secret sql=do-not-expose`
)
}),
})
const result = await buildGfsCopyTools(c)[0]!.execute(
{ drive: 'main', sourceResourceId: 'source', destinationParentId: 'destination', ifMatch: 7 },
''
)
expect(result).toEqual({
success: false,
error: `GFS mutation failed (gfsc ${status}: ${category})`,
})
expect(result.error).not.toContain('/data/')
expect(result.error).not.toContain('sql=')
})
})