Skip to content

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

TypeScript
15.0 KB
Raw Blame
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=')
  })
})