Skip to content

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

TypeScript

fix(gfs): repair CSV journey and report download failures safely

Alfredo Lopez1d12bc5dea36
diff --git a/desktop-app/test/e2e-playwright/gfs-agent-large-file-cli.test.ts b/desktop-app/test/e2e-playwright/gfs-agent-large-file-cli.test.ts
index 0ee71d6cf..514c83dfa 100644
--- a/desktop-app/test/e2e-playwright/gfs-agent-large-file-cli.test.ts
+++ b/desktop-app/test/e2e-playwright/gfs-agent-large-file-cli.test.ts
@@ -10,11 +10,15 @@
* Node command reports the independently generated CSV record count and a
* sentinel located beyond the former 3 MiB boundary.
* - Setup shortcuts: managed agent/folder fixture seeding and the local CSV
- * buffer are named preconditions. No provider-route mock, storage mutation,
+ * file are named preconditions. No provider-route mock, storage mutation,
* direct API trigger, or broad network mock is used.
*/
import { type Locator, type Page, expect, test } from '@playwright/test'
import { randomUUID } from 'node:crypto'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { getGfsChildResourceSummary, getGfsGrantSummary } from '../../../tests/e2e/gfsUiFixtures'
import { exactNameFilter } from './helpers/agentLocators'
import { type ManagedGfsAgent, getManagedAgentDisplayName } from './helpers/gfsAgentDiscovery'
import { assertGfsInfraHealthy } from './helpers/gfsFixtures'
@@ -80,8 +84,7 @@ async function sendTaskAndApproveShell(
const approvalText = await stepper.innerText()
expect(approvalText).toContain('shell_exec')
expect(approvalText).toContain('node')
- if (csv.source === 'synthetic') expect(approvalText).toContain(csv.sentinel!)
- else expect(approvalText).toContain('createHash')
+ expect(approvalText).toContain('createHash')
await approval.click()
await expect(response).toContainText(/ROWS=/, { timeout: RESPONSE_TIMEOUT_MS })
@@ -113,6 +116,8 @@ test.describe('GFS agent large-file CLI journey', () => {
let fixtures: AgentGfsLargeFileFixtures
let agentLabel: string
let csv: GfsLargeCsvFixture
+ let csvUploadPath: string
+ let syntheticDirectory: string | undefined
test.beforeAll(() => {
assertGfsInfraHealthy()
@@ -122,10 +127,21 @@ test.describe('GFS agent large-file CLI journey', () => {
expect(csv.buffer.byteLength).toBe(GFS_LARGE_CSV_SIZE)
if (csv.source === 'synthetic')
expect(csv.buffer.indexOf(csv.sentinel!, 'utf8')).toBeGreaterThan(GFS_OLD_VISUAL_LIMIT)
+ if (csv.sourcePath) csvUploadPath = csv.sourcePath
+ else {
+ // Electron's file picker requires a real local path for getPathForFile.
+ syntheticDirectory = mkdtempSync(join(tmpdir(), 'gfs-agent-large-csv-'))
+ csvUploadPath = join(syntheticDirectory, csv.fileName)
+ writeFileSync(csvUploadPath, csv.buffer, { mode: 0o600 })
+ }
})
test.afterAll(() => {
- fixtures?.cleanup()
+ try {
+ fixtures?.cleanup()
+ } finally {
+ if (syntheticDirectory) rmSync(syntheticDirectory, { recursive: true, force: true })
+ }
})
test('user uploads a 3.8 MiB CSV and approves local processing', async () => {
@@ -148,13 +164,39 @@ test.describe('GFS agent large-file CLI journey', () => {
page.waitForEvent('filechooser', { timeout: 30_000 }),
upload.click(),
])
- await chooser.setFiles(csv.sourcePath!)
+ await chooser.setFiles(csvUploadPath)
await expect(page.getByText(`Uploaded ${csv.fileName}`)).toBeVisible({
timeout: 30_000,
})
await expect(
browser.getByRole('button', { name: `Open ${csv.fileName}`, exact: true })
).toBeVisible({ timeout: 30_000 })
+ const uploaded = getGfsChildResourceSummary({
+ parentResourceId: fixtures.granted.resourceId,
+ name: csv.fileName,
+ })
+ expect(uploaded).toMatchObject({
+ kind: 'file',
+ bytes: GFS_LARGE_CSV_SIZE,
+ deleted: false,
+ })
+ const hostGrant = getGfsGrantSummary({
+ resourceId: fixtures.granted.resourceId,
+ subjectType: 'host',
+ subjectId: fixtures.agent.subjectId,
+ })
+ expect(hostGrant).toMatchObject({ permissions: ['read'], inherit: true })
+ await test.info().attach('gfs-source-identity', {
+ contentType: 'application/json',
+ body: JSON.stringify({
+ resourceId: uploaded!.resourceId,
+ parentResourceId: fixtures.granted.resourceId,
+ version: uploaded!.version,
+ bytes: uploaded!.bytes,
+ hostSubjectId: fixtures.agent.subjectId,
+ hostGrant,
+ }),
+ })
})
let expandButton: Locator
@@ -182,12 +224,15 @@ test.describe('GFS agent large-file CLI journey', () => {
const shellRow = toolStepRow(page, 'shell_exec')
await expect(shellRow).toBeVisible({ timeout: 15_000 })
await expect(shellRow.locator('.stepper-step-duration.state-error')).toHaveCount(0)
- await expect(await stepOutput(shellRow)).toContainText(`ROWS=${csv.recordCount}`)
- await expect(await stepOutput(shellRow)).toContainText(`PROOF=${csv.tailProof}`)
-
- await expect(response).toContainText(`ROWS=${csv.recordCount}`)
- await expect(response).toContainText(`PROOF=${csv.tailProof}`)
- await expect(response).not.toContain('zzzzzzzzzz')
+ const shellOutput = await stepOutput(shellRow)
+ const expectedRows = new RegExp(`\\bROWS=${csv.recordCount}(?=\\s|$)`)
+ const expectedProof = new RegExp(`\\bPROOF=${csv.tailProof}(?=\\s|$)`)
+ await expect(shellOutput).toContainText(expectedRows)
+ await expect(shellOutput).toContainText(expectedProof)
+
+ await expect(response).toContainText(expectedRows)
+ await expect(response).toContainText(expectedProof)
+ await expect(response).not.toContainText('zzzzzzzzzz')
})
await test.step('source remains visible after read-only processing', async () => {
diff --git a/desktop-app/test/e2e-playwright/helpers/gfsLargeFileCsvFixture.ts b/desktop-app/test/e2e-playwright/helpers/gfsLargeFileCsvFixture.ts
index efc19105a..6f43122bc 100644
--- a/desktop-app/test/e2e-playwright/helpers/gfsLargeFileCsvFixture.ts
+++ b/desktop-app/test/e2e-playwright/helpers/gfsLargeFileCsvFixture.ts
@@ -25,8 +25,14 @@ function csvField(value: string): string {
export function buildGfsLargeCsvFixture(): GfsLargeCsvFixture {
const sentinel = `GFS_LARGE_CSV_SENTINEL_${crypto.randomUUID()}`
- let content = `${csvField('id,record name')},${csvField('notes,value')}\n`
+ let content = `${csvField('id')},${csvField('record name')},${csvField(
+ 'notes,value'
+ )},${csvField('value')}\n`
+ let contentBytes = Buffer.byteLength(content, 'utf8')
let recordCount = 1
+ const finalPrefix = `${csvField('record-final')},${csvField('final, sentinel row')},"${sentinel}`
+ const closing = `",${csvField('0')}\n`
+ const minimumFinalLength = Buffer.byteLength(finalPrefix + closing, 'utf8')
for (let index = 1; ; index += 1) {
const multiline = index % 97 === 0
@@ -36,21 +42,14 @@ export function buildGfsLargeCsvFixture(): GfsLargeCsvFixture {
const row = `${csvField(`record-${index}`)},${csvField(
`name, with comma ${index}`
)},${csvField(notes)},${csvField(String(index % 17))}\n`
- const finalPrefix = `${csvField('record-final')},${csvField(
- 'final, sentinel row'
- )},${csvField(`${sentinel}`)}`
- const minimumFinalLength = finalPrefix.length + 2
- if (Buffer.byteLength(content, 'utf8') + row.length + minimumFinalLength > GFS_LARGE_CSV_SIZE)
- break
+ const rowBytes = Buffer.byteLength(row, 'utf8')
+ if (contentBytes + rowBytes + minimumFinalLength > GFS_LARGE_CSV_SIZE) break
content += row
+ contentBytes += rowBytes
recordCount += 1
}
- const finalPrefix = `${csvField('record-final')},${csvField(
- 'final, sentinel row'
- )},${csvField(`${sentinel}`)}`
- const closing = `${csvField('0')}\n`
- const usedBytes = Buffer.byteLength(content, 'utf8') + finalPrefix.length + closing.length
+ const usedBytes = contentBytes + minimumFinalLength
if (usedBytes > GFS_LARGE_CSV_SIZE) throw new Error('GFS large CSV fixture sizing underflow')
const padding = 'z'.repeat(GFS_LARGE_CSV_SIZE - usedBytes)
content += `${finalPrefix}${padding}${closing}`
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 679ca3bdb..05c8310a0 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.483",
+ "version": "0.1.484",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.483",
+ "version": "0.1.484",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@anthropic-ai/sdk": "^0.32.0",
diff --git a/mcp-host/package.json b/mcp-host/package.json
index 01f45cfd7..ea930d873 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.483",
+ "version": "0.1.484",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/internalTools/gfs.ts b/mcp-host/src/internalTools/gfs.ts
index cbb56ebc0..5779e8959 100644
--- a/mcp-host/src/internalTools/gfs.ts
+++ b/mcp-host/src/internalTools/gfs.ts
@@ -1,5 +1,6 @@
import type { FileReferenceV1 } from '@clerum/gfs-interaction-policy'
import type { FileReferenceResolution } from '../agent/fileReferenceResolver'
+import { logger } from '../logger'
import { inspectImage, validateImage } from '../visualInput/imageValidation'
import { VisualInputError } from '../visualInput/policy'
import type {
@@ -630,6 +631,45 @@ export function buildGfsReadTools(
options
)
} catch (error) {
+ // Traces omit tool arguments; retain only public target identifiers
+ // and a bounded failure category, never GFSC bodies or raw errors.
+ const drive =
+ typeof target.drive === 'string' &&
+ target.drive.length > 0 &&
+ target.drive.length <= 64 &&
+ !/[^a-z0-9_-]/.test(target.drive)
+ ? target.drive
+ : undefined
+ const resourceId = normalizeRid(target.resourceId)
+ const status =
+ error instanceof GfscHttpError
+ ? error.status
+ : error instanceof Error
+ ? Number(/^gfsc (\d{3}):/.exec(error.message)?.[1])
+ : Number.NaN
+ logger.warn(
+ {
+ component: 'GfsDownload',
+ ...(drive === undefined ? {} : { drive }),
+ ...(resourceId?.length === 32 ? { resourceId } : {}),
+ ...(Number.isInteger(status) && status >= 100 && status <= 599
+ ? { httpStatus: status }
+ : {}),
+ errorClass:
+ error instanceof GfscHttpError
+ ? 'GfscHttpError'
+ : error instanceof GfsDownloadError
+ ? 'GfsDownloadError'
+ : error instanceof GfsDownloadStoreError
+ ? 'GfsDownloadStoreError'
+ : error instanceof VisualInputError
+ ? 'VisualInputError'
+ : error instanceof Error
+ ? 'Error'
+ : 'unknown',
+ },
+ 'GFS workspace download failed'
+ )
if (expectedVersion !== undefined && versionConflict(error))
return ok({ availability: 'stale', ...target, expectedVersion })
return fail(error)
diff --git a/mcp-host/src/internalTools/gfsDownloadDiagnostics.test.ts b/mcp-host/src/internalTools/gfsDownloadDiagnostics.test.ts
new file mode 100644
index 000000000..5f50067ac
--- /dev/null
+++ b/mcp-host/src/internalTools/gfsDownloadDiagnostics.test.ts
@@ -0,0 +1,210 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { logger } from '../logger'
+import { VisualInputError } from '../visualInput/policy'
+import { type GfscReadClient, buildGfsReadTools } from './gfs'
+import { GfscHttpError } from './gfsClient'
+import { GfsDownloadError } from './gfsContentDownload'
+import { GfsDownloadStore, GfsDownloadStoreError } from './gfsDownloadStore'
+
+const target = { drive: 'main', resourceId: 'a'.repeat(32) }
+const warningMessage = 'GFS workspace download failed'
+// Synthetic private-looking data verifies omission, without real grants or user data.
+const privateDetail =
+ 'unit-only-server-detail /unit-only/storage.csv https://unit-only.invalid/body'
+
+function harness() {
+ const download = vi.fn<NonNullable<GfscReadClient['download']>>()
+ const client = {
+ accessible: vi.fn(),
+ list: vi.fn(),
+ read: vi.fn(),
+ download,
+ stat: vi.fn(),
+ resolve: vi.fn(),
+ } satisfies GfscReadClient
+ const tool = buildGfsReadTools(client, {
+ referencedFiles: new Map(),
+ // The injected download never touches this uninitialized store or these paths.
+ downloadStore: new GfsDownloadStore('/unit-only-host-workspace'),
+ callerIdentity: 'unit-only-caller',
+ callerWorkspacePath: '/unit-only-host-workspace/caller',
+ }).find(item => item.name === 'clerum__gfs_download')!
+ return { tool, download }
+}
+
+beforeEach(() => {
+ vi.spyOn(logger, 'warn').mockImplementation(() => undefined)
+})
+
+afterEach(() => {
+ vi.restoreAllMocks()
+})
+
+describe('GFS download failure diagnostics', () => {
+ it('logs only the normalized public target and HTTP prefix, preserving the redacted failure', async () => {
+ const { tool, download } = harness()
+ const error = Object.assign(new Error(`gfsc 403: ${privateDetail}`), {
+ name: 'unit-only-private-error-name',
+ code: 'unit-only-private-error-code',
+ body: privateDetail,
+ headers: { authorization: 'unit-only-http-identity' },
+ })
+ download.mockRejectedValue(error)
+
+ const result = await tool.execute(
+ {
+ drive: 'main_1',
+ resourceId: 'AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA',
+ content: privateDetail,
+ url: 'https://unit-only.invalid/body',
+ headers: error.headers,
+ },
+ '/unit-only-output-path'
+ )
+
+ expect(result).toEqual({ success: false, error: 'GFS read failed (gfsc 403: forbidden)' })
+ expect(vi.mocked(logger.warn).mock.calls).toEqual([
+ [
+ {
+ component: 'GfsDownload',
+ drive: 'main_1',
+ resourceId: target.resourceId,
+ httpStatus: 403,
+ errorClass: 'Error',
+ },
+ warningMessage,
+ ],
+ ])
+ })
+
+ it('uses a typed HTTP status independently of private message content', async () => {
+ const { tool, download } = harness()
+ const error = new GfscHttpError(403, privateDetail)
+ error.message = privateDetail
+ download.mockRejectedValue(error)
+
+ const result = await tool.execute(target, '/unit-only-output-path')
+
+ expect(result).toEqual({ success: false, error: 'GFS read failed' })
+ expect(vi.mocked(logger.warn).mock.calls).toEqual([
+ [
+ { component: 'GfsDownload', ...target, httpStatus: 403, errorClass: 'GfscHttpError' },
+ warningMessage,
+ ],
+ ])
+ })
+
+ it.each([
+ { drive: 'main/private', resourceId: 'gfs://main/private' },
+ { drive: 'a'.repeat(65), resourceId: '/unit-only/private/path' },
+ { drive: 'main\n', resourceId: `${target.resourceId}\n` },
+ ])('omits unsafe or unbounded target identifiers: %j', async args => {
+ const { tool, download } = harness()
+ download.mockRejectedValue(new Error(`gfsc 403: ${privateDetail}`))
+
+ await tool.execute(args, '/unit-only-output-path')
+
+ expect(vi.mocked(logger.warn).mock.calls).toEqual([
+ [{ component: 'GfsDownload', httpStatus: 403, errorClass: 'Error' }, warningMessage],
+ ])
+ })
+
+ it('does not trust arbitrary status, name or code fields, or an HTTP phrase inside the body', async () => {
+ const { tool, download } = harness()
+ download.mockRejectedValue(
+ Object.assign(new Error(`unit-only-body mentioning gfsc 403: ${privateDetail}`), {
+ status: 403,
+ name: 'GfscHttpError',
+ code: privateDetail,
+ })
+ )
+
+ await tool.execute(target, '/unit-only-output-path')
+
+ expect(vi.mocked(logger.warn).mock.calls).toEqual([
+ [{ component: 'GfsDownload', ...target, errorClass: 'Error' }, warningMessage],
+ ])
+ })
+
+ it.each([99, 600])('omits an out-of-range typed HTTP status (%i)', async status => {
+ const { tool, download } = harness()
+ download.mockRejectedValue(new GfscHttpError(status, privateDetail))
+
+ await tool.execute(target, '/unit-only-output-path')
+
+ expect(vi.mocked(logger.warn).mock.calls).toEqual([
+ [{ component: 'GfsDownload', ...target, errorClass: 'GfscHttpError' }, warningMessage],
+ ])
+ })
+
+ it.each([
+ [new GfsDownloadError('invalid_response'), 'GfsDownloadError'],
+ [new GfsDownloadStoreError('workspace_unavailable'), 'GfsDownloadStoreError'],
+ [new VisualInputError('invalid_response'), 'VisualInputError'],
+ ] as const)(
+ 'retains the known error class without exposing the error object: %s',
+ async (error, errorClass) => {
+ const { tool, download } = harness()
+ download.mockRejectedValue(error)
+
+ const result = await tool.execute(target, '/unit-only-output-path')
+
+ expect(result).toEqual({ success: false, error: error.message })
+ expect(vi.mocked(logger.warn).mock.calls).toEqual([
+ [{ component: 'GfsDownload', ...target, errorClass }, warningMessage],
+ ])
+ }
+ )
+
+ it('keeps a pinned version conflict as the existing stale receipt', async () => {
+ const { tool, download } = harness()
+ download.mockRejectedValue(new GfsDownloadError('version_conflict'))
+
+ const result = await tool.execute({ ...target, expectedVersion: 7 }, '/unit-only-output-path')
+
+ expect(result.success).toBe(true)
+ expect(JSON.parse(result.content!)).toEqual({
+ availability: 'stale',
+ ...target,
+ expectedVersion: 7,
+ })
+ expect(vi.mocked(logger.warn).mock.calls).toEqual([
+ [{ component: 'GfsDownload', ...target, errorClass: 'GfsDownloadError' }, warningMessage],
+ ])
+ })
+
+ it('does not copy fields from a non-Error thrown value', async () => {
+ const { tool, download } = harness()
+ download.mockRejectedValue({ message: privateDetail, status: 403, code: privateDetail })
+
+ await tool.execute(target, '/unit-only-output-path')
+
+ expect(vi.mocked(logger.warn).mock.calls).toEqual([
+ [{ component: 'GfsDownload', ...target, errorClass: 'unknown' }, warningMessage],
+ ])
+ })
+
+ it('does not warn on a successful workspace transfer', async () => {
+ const { tool, download } = harness()
+ download.mockResolvedValue({
+ id: 'unit-download',
+ source: {
+ kind: 'gfs',
+ ...target,
+ gfsUri: `gfs://main/${target.resourceId}`,
+ name: 'unit.csv',
+ version: 7,
+ },
+ path: '.gfs-downloads/unit-download/source',
+ sizeBytes: 1,
+ sha256: 'a'.repeat(64),
+ expiresAt: '2026-10-09T00:00:00.000Z',
+ })
+
+ const result = await tool.execute(target, '/unit-only-output-path')
+
+ expect(result.success).toBe(true)
+ expect(JSON.parse(result.content!).delivery).toBe('workspace_file')
+ expect(logger.warn).not.toHaveBeenCalled()
+ })
+})