Skip to content

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

TypeScript

feat(files): carry Global Files selections as structured FileReferences

Alfredo Lopez7182f8ae8b7c
diff --git a/desktop-app/src/__tests__/appService.rpc.test.ts b/desktop-app/src/__tests__/appService.rpc.test.ts
index 005a0b0e3..780435c51 100644
--- a/desktop-app/src/__tests__/appService.rpc.test.ts
+++ b/desktop-app/src/__tests__/appService.rpc.test.ts
@@ -3,6 +3,7 @@ import fs from 'node:fs/promises'
import { createRequire } from 'node:module'
import os from 'node:os'
import path from 'node:path'
+import { buildGfsFileReference, classifyBytes } from '@clerum/gfs-interaction-policy'
import { AppService } from '../appService.js'
import { __setChatStoreBaseDirForTests } from '../chatStoreBinding.js'
import { ApiError } from '../httpClient.js'
@@ -252,6 +253,94 @@ describe('AppService.invokeHostMessage', () => {
expect(service.rpcClient.invokeHostMessage).toHaveBeenCalledTimes(1)
})
+ describe('structured file references (#666)', () => {
+ const RID = '1234567890abcdef1234567890abcdef'
+
+ function fileReference() {
+ const built = buildGfsFileReference({
+ drive: 'main',
+ resourceId: RID,
+ gfsUri: `gfs://main/${RID}`,
+ version: 3,
+ name: 'plan.md',
+ declaredMediaType: null,
+ byteLength: 120,
+ classification: classifyBytes({
+ bytes: new Uint8Array(0),
+ totalByteLength: 120,
+ declaredMediaType: null,
+ filename: 'plan.md',
+ }),
+ })
+ if (!built.ok) throw new Error(`fixture reference invalid: ${built.code}`)
+ return built.value
+ }
+
+ function serviceWithRpc() {
+ const service = new AppService() as any
+ service.sessionToken = 'session-token'
+ service.me = {
+ id: '00000000-0000-4000-8000-000000000001',
+ email: '[email protected]',
+ name: 'Test User',
+ picture: null,
+ teamId: '00000000-0000-4000-8000-0000000000aa',
+ teamName: 'Test Team',
+ role: 'member',
+ }
+ service.rpcTokenManager = {
+ getOrIssue: vi.fn().mockResolvedValue({ token: 'rpc-test-token' }),
+ clear: vi.fn(),
+ }
+ service.rpcClient = {
+ invokeHostMessage: vi.fn().mockResolvedValue({ success: true, status: 'pending' }),
+ }
+ return service
+ }
+
+ it('forwards the references on the authenticated envelope', async () => {
+ const service = serviceWithRpc()
+ const reference = fileReference()
+
+ await service.invokeHostMessage(
+ 'chatllm',
+ { content: 'Summarize the plan', sender: 'attacker', fileReferences: [reference] },
+ ['chatllm']
+ )
+
+ expect(service.rpcClient.invokeHostMessage).toHaveBeenCalledTimes(1)
+ expect(service.rpcClient.invokeHostMessage.mock.calls[0][2]).toEqual({
+ content: 'Summarize the plan',
+ channelType: 'rpc',
+ channelId: 'chatllm',
+ hostRef: 'chatllm',
+ sender: '00000000-0000-4000-8000-000000000001',
+ metadata: { teamId: '00000000-0000-4000-8000-0000000000aa' },
+ threadId: undefined,
+ attachments: undefined,
+ fileReferences: [reference],
+ })
+ })
+
+ it('rejects non-list references before issuing an RPC token', async () => {
+ const service = serviceWithRpc()
+ const issueToken = vi.spyOn(service, 'issueRpcTokenForHostRefs')
+
+ await expect(
+ service.invokeHostMessage('chatllm', { content: 'hello', fileReferences: {} }, ['chatllm'])
+ ).rejects.toThrow('File references must be a list.')
+ expect(issueToken).toHaveBeenCalledTimes(0)
+ expect(service.rpcClient.invokeHostMessage).toHaveBeenCalledTimes(0)
+
+ // Positive control: a list issues the token and reaches the Host.
+ await service.invokeHostMessage('chatllm', { content: 'hello', fileReferences: [] }, [
+ 'chatllm',
+ ])
+ expect(issueToken).toHaveBeenCalledTimes(1)
+ expect(service.rpcClient.invokeHostMessage).toHaveBeenCalledTimes(1)
+ })
+ })
+
it('switches to a matching directory team before issuing RPC tokens for teamless sessions', async () => {
const service = new AppService() as any
service.desktopGfsUploadStatePath = vi
diff --git a/desktop-app/src/__tests__/ipc.fileReferences.test.ts b/desktop-app/src/__tests__/ipc.fileReferences.test.ts
new file mode 100644
index 000000000..136e47eba
--- /dev/null
+++ b/desktop-app/src/__tests__/ipc.fileReferences.test.ts
@@ -0,0 +1,111 @@
+/**
+ * Issue #666 — the IPC boundary parses structured file references with the
+ * shared FileReference v1 contract and refuses a malformed one instead of
+ * forwarding it to the host.
+ */
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
+import { buildGfsFileReference, classifyBytes } from '@clerum/gfs-interaction-policy'
+import type { AppService } from '../appService.js'
+
+type Handler = (event: unknown, payload: unknown) => Promise<unknown>
+
+const electron = vi.hoisted(() => ({ handlers: new Map<string, Handler>() }))
+
+vi.mock('electron', () => ({
+ BrowserWindow: { fromWebContents: vi.fn(), getAllWindows: vi.fn(() => []) },
+ Notification: vi.fn(),
+ app: { on: vi.fn(), getPath: vi.fn(), getVersion: vi.fn() },
+ clipboard: { writeText: vi.fn() },
+ dialog: { showSaveDialog: vi.fn() },
+ ipcMain: {
+ handle: vi.fn((channel: string, handler: Handler) => {
+ electron.handlers.set(channel, handler)
+ }),
+ on: vi.fn(),
+ removeHandler: vi.fn(),
+ },
+}))
+// ipc.ts only uses AppService as a type at registration; the real module would
+// pull in the whole main-process graph.
+vi.mock('../appService.js', () => ({ AppService: class {} }))
+
+const service = {
+ invokeHostMessage: vi.fn(async (..._args: unknown[]) => ({ taskId: 'task-1' })),
+}
+const trusted = { senderFrame: { url: 'file:///app/index.html' } }
+
+const RID = '1234567890abcdef1234567890abcdef'
+
+function reference(name = 'plan.md') {
+ const built = buildGfsFileReference({
+ drive: 'main',
+ resourceId: RID,
+ gfsUri: `gfs://main/${RID}`,
+ version: 3,
+ name,
+ declaredMediaType: null,
+ byteLength: 120,
+ classification: classifyBytes({
+ bytes: new Uint8Array(0),
+ totalByteLength: 120,
+ declaredMediaType: null,
+ filename: name,
+ }),
+ })
+ if (!built.ok) throw new Error(`fixture reference invalid: ${built.code}`)
+ return built.value
+}
+
+function send(payload: Record<string, unknown>) {
+ const registered = electron.handlers.get('rpc:invokeHostMessage')
+ if (!registered) throw new Error('no IPC handler registered for rpc:invokeHostMessage')
+ return registered(trusted, { hostRef: 'agent-x', payload: { content: 'hi', ...payload } })
+}
+
+beforeAll(async () => {
+ const { registerIpcHandlers } = await import('../ipc.js')
+ registerIpcHandlers(service as unknown as AppService)
+})
+
+afterEach(() => {
+ service.invokeHostMessage.mockClear()
+})
+
+describe('rpc:invokeHostMessage fileReferences', () => {
+ it('forwards the parsed references', async () => {
+ const references = [reference('plan.md'), reference('photo.png')]
+ await send({ fileReferences: references })
+ expect(service.invokeHostMessage).toHaveBeenCalledTimes(1)
+ expect(service.invokeHostMessage).toHaveBeenCalledWith(
+ 'agent-x',
+ expect.objectContaining({ content: 'hi', fileReferences: references }),
+ undefined,
+ undefined
+ )
+ })
+
+ it('leaves a request without references unchanged', async () => {
+ await send({})
+ // Witness: the request reached the service.
+ expect(service.invokeHostMessage).toHaveBeenCalledTimes(1)
+ const request = service.invokeHostMessage.mock.calls[0][1] as Record<string, unknown>
+ expect(request.content).toBe('hi')
+ expect(request).not.toHaveProperty('fileReferences')
+ })
+
+ it.each([
+ ['a non-list value', { id: 'x' }],
+ ['null', null],
+ ['an entry with schemaVersion 2', [{ ...reference(), schemaVersion: 2 }]],
+ ['an entry whose id does not match its source', [{ ...reference(), id: 'gfs:main:other@v3' }]],
+ ['an entry with a path in its name', [{ ...reference(), name: '../plan.md' }]],
+ ])('rejects %s', async (_label, fileReferences) => {
+ await expect(send({ fileReferences })).rejects.toThrow(
+ 'Invalid host message request: fileReferences'
+ )
+ expect(service.invokeHostMessage).toHaveBeenCalledTimes(0)
+ // Control: the same request with a valid reference goes through.
+ await send({ fileReferences: [reference()] })
+ expect(service.invokeHostMessage).toHaveBeenCalledTimes(1)
+ })
+})
diff --git a/desktop-app/src/appService.ts b/desktop-app/src/appService.ts
index 83f1860fb..8da3b7c90 100644
--- a/desktop-app/src/appService.ts
+++ b/desktop-app/src/appService.ts
@@ -3327,6 +3327,9 @@ export class AppService {
if (request.attachments != null && !Array.isArray(request.attachments)) {
throw new Error('Image attachments must be a list.')
}
+ if (request.fileReferences !== undefined && !Array.isArray(request.fileReferences)) {
+ throw new Error('File references must be a list.')
+ }
const effectiveHostRefs = hostRefs && hostRefs.length > 0 ? hostRefs : [targetHostRef]
const rpc = await this.issueRpcTokenForHostRefs(
HOST_WAKEABLE_OPERATION_SCOPES,
@@ -3358,6 +3361,9 @@ export class AppService {
...(request.modelSelectionRevision === undefined
? {}
: { modelSelectionRevision: request.modelSelectionRevision }),
+ // Structured references (#666): parsed at the IPC boundary; rpc-proxy
+ // forwards them and mcp-host resolves each one.
+ ...(request.fileReferences === undefined ? {} : { fileReferences: request.fileReferences }),
}
try {
return await this.rpcClient.invokeHostMessage(
diff --git a/desktop-app/src/ipc.ts b/desktop-app/src/ipc.ts
index 88b88ba2e..f9858b9ea 100644
--- a/desktop-app/src/ipc.ts
+++ b/desktop-app/src/ipc.ts
@@ -10,6 +10,7 @@ import {
import { randomUUID } from 'node:crypto'
import { promises as fs } from 'node:fs'
import path from 'node:path'
+import { parseFileReferenceV1 } from '@clerum/gfs-interaction-policy'
import { AppService } from './appService.js'
import { requireChatStore } from './chatStoreBinding.js'
import { GFS_PREVIEW_MAX_BYTES } from './gfs/previewLimits.js'
@@ -170,6 +171,18 @@ function parseHostMessageRequest(raw: unknown): HostMessageRequest {
) {
throw new Error('Invalid host message request: modelSelectionRevision')
}
+ if (parsed.fileReferences !== undefined) {
+ // Checks shape only; mcp-host enforces the count limit and resolves each reference.
+ if (!Array.isArray(parsed.fileReferences)) {
+ throw new Error('Invalid host message request: fileReferences')
+ }
+ const fileReferences = parsed.fileReferences.map(entry => {
+ const result = parseFileReferenceV1(entry)
+ if (!result.ok) throw new Error('Invalid host message request: fileReferences')
+ return result.value
+ })
+ return { ...parsed, fileReferences }
+ }
return parsed
}
diff --git a/desktop-app/src/types.ts b/desktop-app/src/types.ts
index 42d99f7cf..206a51359 100644
--- a/desktop-app/src/types.ts
+++ b/desktop-app/src/types.ts
@@ -1,3 +1,4 @@
+import type { FileReferenceV1 } from '@clerum/gfs-interaction-policy'
import type { ImageInputDecision } from './imageInputDecision'
export type Role = 'admin' | 'inviter' | 'member'
@@ -538,6 +539,11 @@ export type HostMessageRequest = {
model?: string
/** CAS base captured with a visual message's explicit model choice. */
modelSelectionRevision?: number
+ /**
+ * Issue #666 — Global Files selected in the composer, as structured
+ * references. mcp-host re-authorizes each one before the task exists.
+ */
+ fileReferences?: FileReferenceV1[]
[key: string]: unknown
}
diff --git a/desktop-app/test/e2e-playwright/gfs-agent-file-read.test.ts b/desktop-app/test/e2e-playwright/gfs-agent-file-read.test.ts
index d010e37b9..41fdd0b53 100644
--- a/desktop-app/test/e2e-playwright/gfs-agent-file-read.test.ts
+++ b/desktop-app/test/e2e-playwright/gfs-agent-file-read.test.ts
@@ -236,6 +236,61 @@ test.describe('GFS agent file read (issue #775)', () => {
}
})
+ // Issue #666: the Global Files picker sends the selection as a structured
+ // FileReference; the Host resolves it and lists it in the turn context. The
+ // message names no file, so the read can only come from the reference.
+ // Requires a renderer built with VITE_SHOW_GLOBAL_FILE_SYSTEM_COMPOSER_ITEM=true.
+ test('agent reads a file selected in the Global Files picker (#666)', async () => {
+ const { app, page } = await launchAndLogin(OWNER_EMAIL)
+ try {
+ await test.step('user attaches the file from the Global Files picker', async () => {
+ await enterAgentChat(page, fixtures.agent.name)
+ await startFreshThread(page)
+ await page.getByRole('button', { name: 'Add context' }).click()
+ await page.getByRole('menuitem', { name: 'Global File System' }).click()
+ const picker = page.getByRole('dialog', { name: 'Choose files for this message' })
+ await expect(picker).toBeVisible({ timeout: 10_000 })
+ const fileRow = picker
+ .locator('.composer-global-files-row--file')
+ .filter({ hasText: fixtures.granted.fileName })
+ await expect(fileRow).toBeVisible({ timeout: 20_000 })
+ await fileRow.getByRole('checkbox').check()
+ await picker.getByRole('button', { name: 'Attach 1' }).click()
+ await expect(picker).toHaveCount(0)
+ await expect(
+ page.getByRole('button', { name: `Remove ${fixtures.granted.fileName}` })
+ ).toBeVisible()
+ })
+
+ let expandBtn: import('@playwright/test').Locator
+ await test.step('agent reads the attached file', async () => {
+ const result = await sendGfsTask(
+ page,
+ 'Quote the contents of the attached file verbatim. Do not answer from memory.'
+ )
+ expandBtn = result.expandBtn
+ expect(result.response.toLowerCase()).not.toContain('not_mounted')
+ expect(result.response.toLowerCase()).not.toContain('gfsc 503')
+ expect(result.response.toLowerCase()).not.toContain('fetch failed')
+ })
+
+ await test.step('tool details prove the read of the referenced file', async () => {
+ await expandBtn.click()
+ const readRow = toolStepRow(page, 'gfs_read')
+ await expect(readRow).toBeVisible({ timeout: 10_000 })
+ await expect(readRow.locator('.stepper-step-duration.state-error')).toHaveCount(0)
+ await readRow.click()
+ const readOutput = readRow
+ .locator('xpath=following-sibling::*[@data-testid="step-output-panel"][1]')
+ .locator('.stepper-step-output-code')
+ await expect(readOutput).toBeVisible({ timeout: 10_000 })
+ await expect(readOutput).toContainText(`E2E GFS file fixture: ${fixtures.granted.name}`)
+ })
+ } finally {
+ await app.close()
+ }
+ })
+
test('agent is denied on a file the host has no grant for (403, never 503)', async () => {
const { app, page } = await launchAndLogin(OWNER_EMAIL)
try {
diff --git a/desktop-app/ui/src/components/agents/ComposerGlobalFilesModal/index.tsx b/desktop-app/ui/src/components/agents/ComposerGlobalFilesModal/index.tsx
index be07839cb..7d7db55fa 100644
--- a/desktop-app/ui/src/components/agents/ComposerGlobalFilesModal/index.tsx
+++ b/desktop-app/ui/src/components/agents/ComposerGlobalFilesModal/index.tsx
@@ -216,6 +216,8 @@ export function ComposerGlobalFilesModal({ onAdd, onClose }: ComposerGlobalFiles
drive: entry.drive,
gfsUri: entry.gfsUri,
label: entry.name,
+ version: entry.version,
+ bytes: entry.bytes,
}
const checked = Boolean(selected[id])
return (
diff --git a/desktop-app/ui/src/hooks/domain/__tests__/sendAgentMessage.fileReferences.test.tsx b/desktop-app/ui/src/hooks/domain/__tests__/sendAgentMessage.fileReferences.test.tsx
new file mode 100644
index 000000000..526b7b809
--- /dev/null
+++ b/desktop-app/ui/src/hooks/domain/__tests__/sendAgentMessage.fileReferences.test.tsx
@@ -0,0 +1,103 @@
+// @vitest-environment jsdom
+/**
+ * Issue #666 — a Global Files selection is sent as a structured FileReference v1
+ * in `fileReferences`, next to the prompt line that names it. The prompt no
+ * longer tells the model how to read the file; the Host's turn context does.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, waitFor } from '@testing-library/react'
+import type { ComposerGlobalFileReference } from '../../../uiTypes'
+import { renderController } from './__fixtures__/controllerHarness'
+import { type MockClerum, installMockClerum, uninstallMockClerum } from './__fixtures__/mockClerum'
+
+let clerum: MockClerum
+let uuidCounter = 0
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+const RID = '0123456789abcdef0123456789abcdef'
+
+const planFile: ComposerGlobalFileReference = {
+ id: `global-file:${RID}`,
+ type: 'global_file',
+ resourceId: RID,
+ drive: 'main',
+ gfsUri: `gfs://main/${RID}`,
+ label: 'plan.md',
+ version: 4,
+ bytes: 2048,
+}
+
+beforeEach(() => {
+ uuidCounter = 0
+ vi.spyOn(globalThis.crypto, 'randomUUID').mockImplementation(
+ () => `uuid-${++uuidCounter}` as `${string}-${string}-${string}-${string}-${string}`
+ )
+ clerum = installMockClerum()
+})
+
+afterEach(() => {
+ vi.restoreAllMocks()
+ uninstallMockClerum()
+})
+
+async function settleMount() {
+ await waitFor(() => expect(clerum.chat.getIndex).toHaveBeenCalled())
+}
+
+function sentRequest(): Record<string, unknown> {
+ expect(clerum.rpc.invokeHostMessage).toHaveBeenCalledTimes(1)
+ return clerum.rpc.invokeHostMessage.mock.calls[0]?.[1] as Record<string, unknown>
+}
+
+describe('sendAgentMessage — structured Global Files references (#666)', () => {
+ it('sends the selection as a FileReference v1', async () => {
+ clerum.rpc.invokeHostMessage.mockResolvedValue({ response: 'done' })
+ const { result } = renderController()
+ await settleMount()
+
+ act(() => {
+ result.current.handleAddComposerReferenceAttachments([planFile])
+ })
+ await act(async () => {
+ await result.current.handleSendAgentMessage('Summarize the plan')
+ })
+
+ const request = sentRequest()
+ expect(request.fileReferences).toEqual([
+ expect.objectContaining({
+ schemaVersion: 1,
+ id: `gfs:main:${RID}@v4`,
+ source: {
+ kind: 'gfs',
+ drive: 'main',
+ resourceId: RID,
+ gfsUri: `gfs://main/${RID}`,
+ version: 4,
+ },
+ name: 'plan.md',
+ class: 'markdown',
+ byteLength: 2048,
+ }),
+ ])
+ expect(request.content).toContain(
+ `Global Files: plan.md (gfs://main/${RID}). These files were explicitly selected by the user.`
+ )
+ expect(request.content).not.toContain('clerum__gfs_read')
+ })
+
+ it('sends no fileReferences field without a Global Files selection', async () => {
+ clerum.rpc.invokeHostMessage.mockResolvedValue({ response: 'done' })
+ const { result } = renderController()
+ await settleMount()
+
+ await act(async () => {
+ await result.current.handleSendAgentMessage('plain question')
+ })
+
+ // Witness: the message was sent with its content.
+ const request = sentRequest()
+ expect(request.content).toBe('plain question')
+ expect(request).not.toHaveProperty('fileReferences')
+ })
+})
diff --git a/desktop-app/ui/src/hooks/domain/useAgentChatController.ts b/desktop-app/ui/src/hooks/domain/useAgentChatController.ts
index d37893f25..7cc458608 100644
--- a/desktop-app/ui/src/hooks/domain/useAgentChatController.ts
+++ b/desktop-app/ui/src/hooks/domain/useAgentChatController.ts
@@ -16,6 +16,7 @@ import {
getComposerDraftRevision,
setComposerDraft,
} from '@lib/composerDraftStore'
+import { buildComposerFileReferences } from '@lib/composerFileReferences'
import { buildComposerRequestContent } from '@lib/composerReferencesPrompt'
import {
confirmHostModelSelectionFromSend,
@@ -2703,6 +2704,7 @@ export function useAgentChatController({
if (sendScope !== sendScopeGeneration.current) return
const pendingModel = pendingModelForSend
const requestModel = requestModelForRetention
+ const fileReferences = buildComposerFileReferences(effectiveReferences)
const request = {
content: effectiveContentForRequest,
channelType: 'rpc',
@@ -2716,6 +2718,7 @@ export function useAgentChatController({
...(visualModelRevisionForSend === undefined
? {}
: { modelSelectionRevision: visualModelRevisionForSend }),
+ ...(fileReferences.length > 0 ? { fileReferences } : {}),
}
const response = await window.clerum.rpc.invokeHostMessage(
diff --git a/desktop-app/ui/src/lib/__tests__/composerFileReferences.test.ts b/desktop-app/ui/src/lib/__tests__/composerFileReferences.test.ts
new file mode 100644
index 000000000..8722c6a8d
--- /dev/null
+++ b/desktop-app/ui/src/lib/__tests__/composerFileReferences.test.ts
@@ -0,0 +1,116 @@
+import { describe, expect, it } from 'vitest'
+import { parseFileReferenceV1 } from '@clerum/gfs-interaction-policy'
+import type { ComposerGlobalFileReference, ComposerReferenceAttachment } from '../../uiTypes'
+import { buildComposerFileReferences } from '../composerFileReferences'
+
+const RID = '0123456789abcdef0123456789abcdef'
+
+function globalFile(
+ overrides: Partial<ComposerGlobalFileReference> = {}
+): ComposerGlobalFileReference {
+ return {
+ id: `global-file:${RID}`,
+ type: 'global_file',
+ resourceId: RID,
+ drive: 'main',
+ gfsUri: `gfs://main/${RID}`,
+ label: 'plan.md',
+ version: 4,
+ bytes: 2048,
+ ...overrides,
+ }
+}
+
+describe('buildComposerFileReferences (#666)', () => {
+ it('turns a Global Files selection into a FileReference v1', () => {
+ const [reference] = buildComposerFileReferences([globalFile()])
+
+ expect(reference).toEqual({
+ schemaVersion: 1,
+ id: `gfs:main:${RID}@v4`,
+ source: {
+ kind: 'gfs',
+ drive: 'main',
+ resourceId: RID,
+ gfsUri: `gfs://main/${RID}`,
+ version: 4,
+ },
+ name: 'plan.md',
+ declaredMediaType: null,
+ detectedMediaType: 'text/markdown',
+ class: 'markdown',
+ detection: 'declared',
+ mismatch: false,
+ byteLength: 2048,
+ textReadable: true,
+ reader: 'text',
+ modelImageInput: 'unsupported',
+ })
+ // The value is what the IPC boundary accepts.
+ expect(parseFileReferenceV1(reference)).toEqual({ ok: true, value: reference })
+ })
+
+ it('classifies by file name when the picker lists no media type', () => {
+ const references = buildComposerFileReferences([
+ globalFile({ label: 'photo.png' }),
+ globalFile({ label: 'report.pdf' }),
+ globalFile({ label: 'archive.bin' }),
+ ])
+
+ expect(references.map(r => [r.class, r.reader, r.modelImageInput])).toEqual([
+ ['png', 'none', 'candidate'],
+ ['pdf', 'none', 'unsupported'],
+ ['binary_unsupported', 'none', 'unsupported'],
+ ])
+ })
+
+ it('keeps the selection order and ignores other reference kinds', () => {
+ const second = `fedcba9876543210fedcba9876543210`
+ const references: ComposerReferenceAttachment[] = [
+ { id: 'connector:github', type: 'connector', name: 'github', label: 'GitHub' },
+ globalFile(),
+ {
+ id: 'agent-file:ctx-1:assets:/a.txt:file',
+ type: 'agent_file',
+ contextId: 'ctx-1',
+ filesystemName: 'assets',
+ path: '/a.txt',
+ kind: 'file',
+ label: 'assets/a.txt',
+ },
+ globalFile({
+ resourceId: second,
+ gfsUri: `gfs://main/${second}`,
+ label: 'notes.txt',
+ version: 1,
+ }),
+ ]
+
+ expect(buildComposerFileReferences(references).map(r => r.id)).toEqual([
+ `gfs:main:${RID}@v4`,
+ `gfs:main:${second}@v1`,
+ ])
+ })
+
+ it('returns no references when nothing from Global Files is selected', () => {
+ const references: ComposerReferenceAttachment[] = [
+ { id: 'connector:github', type: 'connector', name: 'github', label: 'GitHub' },
+ ]
+ const result = buildComposerFileReferences(references)
+ // Witness: the call returned a list, not undefined.
+ expect(Array.isArray(result)).toBe(true)
+ expect(result).toHaveLength(0)
+ })
+
+ it('throws instead of sending a selection the contract refuses', () => {
+ expect(() => buildComposerFileReferences([globalFile({ label: 'drafts/plan.md' })])).toThrow(
+ /^Global file reference is invalid \(FILE_REFERENCE_INVALID\)/
+ )
+ // The classifier refuses an impossible size before the contract sees it.
+ expect(() => buildComposerFileReferences([globalFile({ bytes: -1 })])).toThrow(
+ /totalByteLength/
+ )
+ // Control: the unmodified selection builds.
+ expect(buildComposerFileReferences([globalFile()])).toHaveLength(1)
+ })
+})
diff --git a/desktop-app/ui/src/lib/__tests__/composerReferencesPrompt.test.ts b/desktop-app/ui/src/lib/__tests__/composerReferencesPrompt.test.ts
index 8dbcc3fdc..4bde2663e 100644
--- a/desktop-app/ui/src/lib/__tests__/composerReferencesPrompt.test.ts
+++ b/desktop-app/ui/src/lib/__tests__/composerReferencesPrompt.test.ts
@@ -37,6 +37,8 @@ describe('composer references prompt helpers', () => {
drive: 'main',
gfsUri: 'gfs://main/0123456789abcdef',
label: 'quarterly-report.pdf',
+ version: 2,
+ bytes: 4096,
},
]
@@ -48,8 +50,13 @@ describe('composer references prompt helpers', () => {
expect(prompt).toContain('prefix before "__" exactly matches')
expect(prompt).toContain('Agent Files: assets/invite.png')
expect(prompt).toContain('clerum__context_files_read')
- expect(prompt).toContain('Global Files: quarterly-report.pdf (gfs://main/0123456789abcdef)')
- expect(prompt).toContain('clerum__gfs_resolve')
+ // The Global Files line names the selection; the read instruction now comes
+ // from the Host's turn context for the structured fileReferences (#666).
+ expect(prompt).toContain(
+ 'Global Files: quarterly-report.pdf (gfs://main/0123456789abcdef). These files were explicitly selected by the user.'
+ )
+ expect(prompt).not.toContain('clerum__gfs_resolve')
+ expect(prompt).not.toContain('clerum__gfs_read')
})
it('leaves request content unchanged when no references are attached', () => {
diff --git a/desktop-app/ui/src/lib/composerFileReferences.ts b/desktop-app/ui/src/lib/composerFileReferences.ts
new file mode 100644
index 000000000..1de376990
--- /dev/null
+++ b/desktop-app/ui/src/lib/composerFileReferences.ts
@@ -0,0 +1,44 @@
+import {
+ type FileReferenceV1,
+ buildGfsFileReference,
+ classifyBytes,
+} from '@clerum/gfs-interaction-policy'
+import type { ComposerGlobalFileReference, ComposerReferenceAttachment } from '../uiTypes'
+
+/**
+ * Builds the structured FileReference v1 for one Global Files selection
+ * (#666). The picker lists no media type and no bytes, so the class comes
+ * from the file name alone (`detection: 'declared'`); mcp-host resolves the
+ * reference against GFS before the model sees it.
+ */
+function globalFileReference(reference: ComposerGlobalFileReference): FileReferenceV1 {
+ const built = buildGfsFileReference({
+ drive: reference.drive,
+ resourceId: reference.resourceId,
+ gfsUri: reference.gfsUri,
+ version: reference.version,
+ name: reference.label,
+ declaredMediaType: null,
+ byteLength: reference.bytes,
+ classification: classifyBytes({
+ bytes: new Uint8Array(0),
+ totalByteLength: reference.bytes,
+ declaredMediaType: null,
+ filename: reference.label,
+ }),
+ })
+ if (!built.ok) {
+ throw new Error(`Global file reference is invalid (${built.code}): ${built.message}`)
+ }
+ return built.value
+}
+
+export function buildComposerFileReferences(
+ references: ComposerReferenceAttachment[]
+): FileReferenceV1[] {
+ return references
+ .filter(
+ (reference): reference is ComposerGlobalFileReference => reference.type === 'global_file'
+ )
+ .map(globalFileReference)
+}
diff --git a/desktop-app/ui/src/lib/composerReferencesPrompt.ts b/desktop-app/ui/src/lib/composerReferencesPrompt.ts
index dbb6c70a6..bcf8acad0 100644
--- a/desktop-app/ui/src/lib/composerReferencesPrompt.ts
+++ b/desktop-app/ui/src/lib/composerReferencesPrompt.ts
@@ -90,8 +90,10 @@ export function buildComposerReferencesPromptSection(
}
if (globalFiles.length) {
+ // The files travel as structured fileReferences (#666); the Host lists them
+ // in the turn context with how to read them, so this line only names them.
lines.push(
- `Global Files: ${globalFiles.join(', ')}. These files were explicitly selected by the user. Use clerum__gfs_resolve for each gfs:// URI, then clerum__gfs_read with its drive and resourceId before relying on its contents.`
+ `Global Files: ${globalFiles.join(', ')}. These files were explicitly selected by the user.`
)
}
diff --git a/desktop-app/ui/src/uiTypes.ts b/desktop-app/ui/src/uiTypes.ts
index b14c07e5b..0cca0a293 100644
--- a/desktop-app/ui/src/uiTypes.ts
+++ b/desktop-app/ui/src/uiTypes.ts
@@ -295,6 +295,9 @@ export type ComposerGlobalFileReference = {
drive: string
gfsUri: string
label: string
+ /** Version and size the picker listed; they become the structured FileReference (#666). */
+ version: number
+ bytes: number
}
export type ComposerReferenceAttachment =
diff --git a/external-rest-api/src/releaseManifest.ts b/external-rest-api/src/releaseManifest.ts
index fdc83883b..48d93c83f 100644
--- a/external-rest-api/src/releaseManifest.ts
+++ b/external-rest-api/src/releaseManifest.ts
@@ -9,7 +9,7 @@ export type ReleaseManifest = {
export const releaseManifest: ReleaseManifest = {
releaseId: 'v0.9.0',
externalRestApiVersion: '0.1.84',
- rpcProxyVersion: '0.1.90',
+ rpcProxyVersion: '0.1.91',
desktopVersion: '0.9.0',
minimumDesktopVersion: '0.1.252',
}
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index b0fd768c4..308c9f507 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.442",
+ "version": "0.1.443",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.442",
+ "version": "0.1.443",
"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 716888d5d..05df596ab 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.442",
+ "version": "0.1.443",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/__tests__/messageHandler.duplicate.test.ts b/mcp-host/src/__tests__/messageHandler.duplicate.test.ts
index bb6b619a7..6caa875b5 100644
--- a/mcp-host/src/__tests__/messageHandler.duplicate.test.ts
+++ b/mcp-host/src/__tests__/messageHandler.duplicate.test.ts
@@ -12,6 +12,7 @@
*/
import { describe, expect, it, vi } from 'vitest'
import { EventEmitter } from 'events'
+import { buildGfsFileReference, classifyBytes } from '@clerum/gfs-interaction-policy'
import type { Attachment } from '../core/types'
import { TaskLifecycle } from '../lifecycle/taskLifecycle'
import { logger } from '../logger'
@@ -330,6 +331,109 @@ describe('IncomingMessageHandler — duplicate delivery keeps acceptedAttachment
})
})
+/**
+ * #666 D13 — a replay names the file references the first delivery resolved,
+ * whatever their availability, exactly as the first response did.
+ */
+describe('IncomingMessageHandler — duplicate delivery keeps acceptedFileReferenceIds', () => {
+ function reference(resourceId: string) {
+ const built = buildGfsFileReference({
+ drive: 'main',
+ resourceId,
+ gfsUri: `gfs://main/${resourceId}`,
+ version: 3,
+ name: 'notes.md',
+ declaredMediaType: 'text/markdown',
+ byteLength: 12,
+ classification: classifyBytes({
+ bytes: new Uint8Array(0),
+ totalByteLength: 12,
+ declaredMediaType: 'text/markdown',
+ filename: 'notes.md',
+ }),
+ })
+ if (!built.ok) throw new Error(built.message)
+ return built.value
+ }
+ const available = reference('1234567890abcdef1234567890abcdef')
+ const stale = reference('abcdefabcdefabcdefabcdefabcdefab')
+
+ function resolvedMessage(messageId: string): IncomingMessage {
+ return {
+ ...createTestMessage(messageId),
+ fileReferences: [available, stale],
+ fileReferenceResolutions: [
+ { availability: 'available', reference: available },
+ { availability: 'stale', reference: stale, resolvedVersion: 4 },
+ ],
+ }
+ }
+
+ it('replays them for a duplicate of a COMPLETED task', async () => {
+ const deps = createMockDeps()
+ const message = resolvedMessage('msg-ref-completed')
+ const first = new IncomingMessageHandler(message, deps)
+ const firstPromise = first.execute()
+ await new Promise(r => setTimeout(r, 10))
+ const task = deps.messageQueue.dequeue()!
+ task.result = { response: 'first answer', model: 'test-model' }
+ deps.messageQueue.completeTask(task)
+ await task.responseCallback!({ response: 'first answer' })
+ await firstPromise
+
+ const second = await new IncomingMessageHandler(message, deps).execute()
+
+ expect(second).toMatchObject({
+ success: true,
+ status: 'completed',
+ taskId: task.id,
+ acceptedFileReferenceIds: [available.id, stale.id],
+ })
+ expect(deps.taskLifecycle.getStats().total).toBe(1)
+ })
+
+ it('replays them for a duplicate while the original is still processing', async () => {
+ const deps = createMockDeps()
+ const message = resolvedMessage('msg-ref-inflight')
+ const first = new IncomingMessageHandler(message, deps)
+ const firstPromise = first.execute()
+ await new Promise(r => setTimeout(r, 10))
+ const task = deps.messageQueue.dequeue()!
+
+ const second = await new IncomingMessageHandler(message, deps).execute()
+
+ expect(second).toMatchObject({
+ success: true,
+ status: 'pending',
+ taskId: task.id,
+ acceptedFileReferenceIds: [available.id, stale.id],
+ })
+ await task.responseCallback!({ response: 'done' })
+ await firstPromise
+ })
+
+ it('records only resolutions, never the raw references a caller sent', async () => {
+ const deps = createMockDeps()
+ const message: IncomingMessage = {
+ ...createTestMessage('msg-ref-unresolved'),
+ fileReferences: [available],
+ }
+ const first = new IncomingMessageHandler(message, deps)
+ first.executeAsync()
+ const task = deps.messageQueue.dequeue()!
+ task.result = { response: 'plain answer', model: 'test-model' }
+ deps.messageQueue.completeTask(task)
+ await task.responseCallback!({ response: 'plain answer' })
+
+ const second = new IncomingMessageHandler(message, deps).executeAsync()
+
+ // Witness: the duplicate replayed the completed outcome.
+ expect(second.status).toBe('completed')
+ expect(deps.taskLifecycle.get(task.id)?.acceptedFileReferenceIds).toEqual([])
+ expect('acceptedFileReferenceIds' in second).toBe(false)
+ })
+})
+
/**
* Regression: stateless `pendingResults` idle gauge vs C3 recoverability cache.
*
diff --git a/mcp-host/src/agent/__tests__/fileReference.turnContext.integration.test.ts b/mcp-host/src/agent/__tests__/fileReference.turnContext.integration.test.ts
new file mode 100644
index 000000000..b400f254b
--- /dev/null
+++ b/mcp-host/src/agent/__tests__/fileReference.turnContext.integration.test.ts
@@ -0,0 +1,176 @@
+/**
+ * #666 — resolved file references reach the model through the real
+ * TaskExecutor as `referenced_file` lines in the turn-context block, with the
+ * prompt cache on or off. Only the model is a double.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { buildGfsFileReference, classifyBytes } from '@clerum/gfs-interaction-policy'
+import { config as appConfig } from '../../config'
+import { ConversationManager } from '../../core/conversation/conversation'
+import { SimpleEventEmitter } from '../../core/orchestration/eventEmitter'
+import { REFERENCED_FILES_INSTRUCTION } from '../../core/orchestration/turnContext'
+import { type ChatMessage, FinishReason } from '../../core/types'
+import { TaskLifecycle } from '../../lifecycle/taskLifecycle'
+import type { SingleTurnProvider } from '../../llm/types'
+import { McpManager } from '../../mcp/manager'
+import type { Task } from '../../queue/types'
+import type { FileReferenceResolution } from '../fileReferenceResolver'
+import { TaskExecutor, type TaskExecutorDeps } from '../taskExecutor'
+
+const RID = '1234567890abcdef1234567890abcdef'
+const RID_2 = 'abcdefabcdefabcdefabcdefabcdefab'
+const usage = { input_tokens: 1, output_tokens: 1, total_tokens: 2 }
+
+function gfsReference(resourceId: string, version: number) {
+ const built = buildGfsFileReference({
+ drive: 'main',
+ resourceId,
+ gfsUri: `gfs://main/${resourceId}`,
+ version,
+ name: 'plan.md',
+ declaredMediaType: 'text/markdown',
+ byteLength: 120,
+ classification: classifyBytes({
+ bytes: new Uint8Array(0),
+ totalByteLength: 120,
+ declaredMediaType: 'text/markdown',
+ filename: 'plan.md',
+ }),
+ })
+ if (!built.ok) throw new Error(built.message)
+ return built.value
+}
+
+function lastUserText(messages: ChatMessage[]): string {
+ const user = [...messages].reverse().find(message => message.role === 'user')
+ if (!user) throw new Error('the provider received no user message')
+ return user.content ?? ''
+}
+
+async function runTask(fileReferenceResolutions: FileReferenceResolution[] | undefined) {
+ const providerCalls: ChatMessage[][] = []
+ const provider: SingleTurnProvider = {
+ getProviderType: () => 'openai',
+ classifyError: () => {
+ throw new Error('Unexpected provider failure')
+ },
+ completeSingleTurn: async () => {
+ throw new Error('Unexpected non-tool completion')
+ },
+ completeSingleTurnWithTools: async messages => {
+ providerCalls.push(structuredClone(messages))
+ return { content: 'done', tool_calls: null, usage, finish_reason: FinishReason.Stop }
+ },
+ }
+ const task: Task = {
+ id: `file-reference-${fileReferenceResolutions?.length ?? 0}`,
+ source: 'channel',
+ status: 'pending',
+ priority: 'normal',
+ createdAt: new Date(),
+ sourceMessage: {
+ sender: 'authenticated-user',
+ content: 'Summarize the referenced plan',
+ channelType: 'rpc',
+ channelId: 'isolated-channel',
+ messageId: 'message-1',
+ timestamp: new Date().toISOString(),
+ hostRef: 'fixture-host',
+ ...(fileReferenceResolutions
+ ? {
+ fileReferences: fileReferenceResolutions.map(resolution => resolution.reference),
+ fileReferenceResolutions,
+ }
+ : {}),
+ },
+ conversationHistory: [
+ { role: 'user', content: 'Summarize the referenced plan', timestamp: new Date() },
+ ],
+ responseCallback: vi.fn(async () => {}),
+ }
+ const lifecycle = new TaskLifecycle()
+ lifecycle.register(task)
+ const deps: TaskExecutorDeps = {
+ conversationManager: new ConversationManager(),
+ llmProvider: provider,
+ mcpManager: new McpManager(),
+ workspaceService: undefined,
+ modelName: 'test-model',
+ approvalConfig: undefined,
+ config: {
+ maxTaskDuration: 300000,
+ maxToolCallsPerTask: 10,
+ autoStart: true,
+ taskDelay: 0,
+ approvalTimeout: 300000,
+ },
+ coreEvents: new SimpleEventEmitter(),
+ cronScheduler: null,
+ taskLifecycle: lifecycle,
+ onApprovalNeeded: vi.fn(),
+ onComplete: vi.fn(),
+ onFail: vi.fn(),
+ dynamicEnvProvider: () => ({}),
+ }
+ const executor = new TaskExecutor(task, deps)
+ await executor.run()
+ return { deps, executor, providerCalls }
+}
+
+describe('referenced_file lines through a complete task (#666)', () => {
+ const saved = {
+ enableApproval: appConfig.enableApproval,
+ dynamicToolsEnabled: appConfig.dynamicToolsEnabled,
+ promptCacheEnabled: appConfig.promptCacheEnabled,
+ }
+
+ afterEach(() => {
+ Object.assign(appConfig, saved)
+ })
+
+ it.each([true, false])(
+ 'lists every resolved reference with the prompt cache %s',
+ async promptCacheEnabled => {
+ Object.assign(appConfig, {
+ enableApproval: false,
+ dynamicToolsEnabled: false,
+ promptCacheEnabled,
+ })
+ const available = gfsReference(RID, 3)
+ const stale = gfsReference(RID_2, 1)
+ const { deps, executor, providerCalls } = await runTask([
+ { availability: 'available', reference: available },
+ { availability: 'stale', reference: stale, resolvedVersion: 4 },
+ ])
+
+ expect(deps.onFail).not.toHaveBeenCalled()
+ expect(executor.executorState).toBe('completed')
+ expect(providerCalls).toHaveLength(1)
+ const text = lastUserText(providerCalls[0]!)
+ expect(text.startsWith('<turn-context>')).toBe(true)
+ expect(text).toContain(
+ `referenced_file: id=${available.id} name="plan.md" source=gfs drive=main resourceId=${RID} version=3 class=${available.class} bytes=120 availability=available\n`
+ )
+ expect(text).toContain(
+ `referenced_file: id=${stale.id} name="plan.md" source=gfs drive=main resourceId=${RID_2} version=1 class=${stale.class} bytes=120 availability=stale code=FILE_REFERENCE_STALE current_version=4\n`
+ )
+ expect(text).toContain(REFERENCED_FILES_INSTRUCTION)
+ expect(text.endsWith('Summarize the referenced plan')).toBe(true)
+ }
+ )
+
+ it('adds no turn-context block with the prompt cache off and no reference', async () => {
+ Object.assign(appConfig, {
+ enableApproval: false,
+ dynamicToolsEnabled: false,
+ promptCacheEnabled: false,
+ })
+ const { deps, executor, providerCalls } = await runTask(undefined)
+
+ // Witness: the task ran and the model received the user's message.
+ expect(deps.onFail).not.toHaveBeenCalled()
+ expect(executor.executorState).toBe('completed')
+ expect(providerCalls).toHaveLength(1)
+ expect(lastUserText(providerCalls[0]!)).toBe('Summarize the referenced plan')
+ })
+})
diff --git a/mcp-host/src/agent/__tests__/fileReferenceResolver.test.ts b/mcp-host/src/agent/__tests__/fileReferenceResolver.test.ts
new file mode 100644
index 000000000..4c3ca0b25
--- /dev/null
+++ b/mcp-host/src/agent/__tests__/fileReferenceResolver.test.ts
@@ -0,0 +1,416 @@
+/**
+ * #666 — route-level parsing and gfsc resolution of structured file references.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import {
+ type FileReferenceV1,
+ buildAttachmentFileReference,
+ buildGfsFileReference,
+ classifyBytes,
+} from '@clerum/gfs-interaction-policy'
+import { GfscHttpError } from '../../internalTools/gfsClient'
+import { VISUAL_INPUT_LIMITS } from '../../visualInput/policy'
+import {
+ FILE_REFERENCE_AVAILABILITY_CODES,
+ type FileReferenceGfscClient,
+ parseIncomingFileReferences,
+ referencedFilesForTurnContext,
+ resolveFileReferences,
+} from '../fileReferenceResolver'
+
+const RID = '1234567890abcdef1234567890abcdef'
+const RID_2 = 'abcdefabcdefabcdefabcdefabcdefab'
+
+function gfsReference(
+ overrides: { resourceId?: string; version?: number; byteLength?: number; drive?: string } = {}
+): FileReferenceV1 {
+ const resourceId = overrides.resourceId ?? RID
+ const drive = overrides.drive ?? 'main'
+ const byteLength = overrides.byteLength ?? 120
+ const built = buildGfsFileReference({
+ drive,
+ resourceId,
+ gfsUri: `gfs://${drive}/${resourceId.replace(/-/g, '').toLowerCase()}`,
+ version: overrides.version ?? 3,
+ name: 'notes.md',
+ declaredMediaType: 'text/markdown',
+ byteLength,
+ classification: classifyBytes({
+ bytes: new Uint8Array(0),
+ totalByteLength: byteLength,
+ declaredMediaType: 'text/markdown',
+ filename: 'notes.md',
+ }),
+ })
+ if (!built.ok) throw new Error(built.message)
+ return built.value
+}
+
+function attachmentReference(): FileReferenceV1 {
+ const bytes = new TextEncoder().encode('hello')
+ const built = buildAttachmentFileReference({
+ attachmentId: 'a1',
+ messageId: 'm1',
+ name: 'hello.txt',
+ declaredMediaType: 'text/plain',
+ byteLength: bytes.length,
+ digestHex: '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824',
+ classification: classifyBytes({
+ bytes,
+ totalByteLength: bytes.length,
+ declaredMediaType: 'text/plain',
+ filename: 'hello.txt',
+ }),
+ })
+ if (!built.ok) throw new Error(built.message)
+ return built.value
+}
+
+function view(fields: Record<string, unknown> = {}) {
+ return {
+ ok: true,
+ data: {
+ resourceId: RID,
+ rid: RID,
+ drive: 'main',
+ gfsUri: `gfs://main/${RID}`,
+ kind: 'file',
+ name: 'notes.md',
+ version: 3,
+ bytes: 120,
+ ...fields,
+ },
+ }
+}
+
+function client(answer: (uri: string) => unknown | Promise<unknown>) {
+ const resolve = vi.fn<FileReferenceGfscClient['resolve']>(async ({ uri }) => answer(uri))
+ return { resolve } satisfies FileReferenceGfscClient
+}
+
+describe('parseIncomingFileReferences (#666)', () => {
+ it('treats an absent field as a message without references', () => {
+ expect(parseIncomingFileReferences(undefined, 10)).toEqual({ ok: true, references: [] })
+ })
+
+ it('returns the parsed references in order', () => {
+ const first = gfsReference()
+ const second = gfsReference({ resourceId: RID_2 })
+ const parsed = parseIncomingFileReferences([first, second], 10)
+ expect(parsed).toEqual({ ok: true, references: [first, second] })
+ })
+
+ it.each([null, {}, 'gfs://main/x', 3])('rejects a non-list value %j', value => {
+ expect(parseIncomingFileReferences(value, 10)).toMatchObject({
+ ok: false,
+ code: 'FILE_REFERENCE_INVALID',
+ })
+ })
+
+ it('rejects more references than the limit, and accepts exactly the limit', () => {
+ const refs = [gfsReference(), gfsReference({ resourceId: RID_2 })]
+ expect(parseIncomingFileReferences(refs, 2)).toMatchObject({ ok: true })
+ expect(parseIncomingFileReferences(refs, 1)).toMatchObject({
+ ok: false,
+ code: 'FILE_REFERENCE_INVALID',
+ })
+ })
+
+ it('keeps the schema-version code from the parser', () => {
+ const ref = { ...gfsReference(), schemaVersion: 2 }
+ expect(parseIncomingFileReferences([ref], 10)).toMatchObject({
+ ok: false,
+ code: 'FILE_REFERENCE_SCHEMA_VERSION_UNSUPPORTED',
+ })
+ })
+
+ it('rejects a reference whose id does not match its source', () => {
+ const ref = { ...gfsReference(), id: `gfs:main:${RID}@v9` }
+ expect(parseIncomingFileReferences([ref], 10)).toMatchObject({
+ ok: false,
+ code: 'FILE_REFERENCE_INVALID',
+ })
+ })
+
+ it('rejects the same reference twice', () => {
+ const ref = gfsReference()
+ expect(parseIncomingFileReferences([ref, ref], 10)).toMatchObject({
+ ok: false,
+ code: 'FILE_REFERENCE_INVALID',
+ message: 'Each file reference must appear once.',
+ })
+ })
+
+ it.each([
+ ['another drive', `gfs://other/${RID}`],
+ ['another resource', `gfs://main/${RID_2}`],
+ ])('rejects a gfsUri that names %s', (_label, gfsUri) => {
+ const ref = gfsReference()
+ const tampered = { ...ref, source: { ...ref.source, gfsUri } }
+ expect(parseIncomingFileReferences([tampered], 10)).toMatchObject({
+ ok: false,
+ code: 'FILE_REFERENCE_INVALID',
+ message: 'The gfsUri of a file reference must name its drive and resourceId.',
+ })
+ })
+
+ it('accepts a dashed resourceId whose gfsUri carries the normalized rid', () => {
+ const dashed = '12345678-90ab-cdef-1234-567890abcdef'
+ expect(parseIncomingFileReferences([gfsReference({ resourceId: dashed })], 10)).toMatchObject({
+ ok: true,
+ })
+ })
+})
+
+describe('resolveFileReferences (#666)', () => {
+ it('reports available when gfsc returns the same file at the same version', async () => {
+ const gfsc = client(() => view())
+ const ref = gfsReference()
+ const result = await resolveFileReferences([ref], gfsc)
+ expect(result).toEqual({
+ ok: true,
+ resolutions: [{ availability: 'available', reference: ref }],
+ })
+ expect(gfsc.resolve).toHaveBeenCalledTimes(1)
+ expect(gfsc.resolve.mock.calls[0]![0]).toEqual({ uri: `gfs://main/${RID}` })
+ expect(gfsc.resolve.mock.calls[0]![1].signal).toBeInstanceOf(AbortSignal)
+ })
+
+ it('reports stale with the current version when the file changed', async () => {
+ const gfsc = client(() => view({ version: 4, bytes: 999 }))
+ const result = await resolveFileReferences([gfsReference()], gfsc)
+ expect(result).toMatchObject({
+ ok: true,
+ resolutions: [{ availability: 'stale', resolvedVersion: 4 }],
+ })
+ })
+
+ it('reports not_a_file for a directory', async () => {
+ const gfsc = client(() => view({ kind: 'directory', bytes: 0 }))
+ const result = await resolveFileReferences([gfsReference()], gfsc)
+ expect(result).toMatchObject({ ok: true, resolutions: [{ availability: 'not_a_file' }] })
+ })
+
+ it('reports too_large above the per-file ceiling, and available at it', async () => {
+ const limit = VISUAL_INPUT_LIMITS.fileBytes
+ const atLimit = await resolveFileReferences(
+ [gfsReference({ byteLength: limit })],
+ client(() => view({ bytes: limit }))
+ )
+ expect(atLimit).toMatchObject({ ok: true, resolutions: [{ availability: 'available' }] })
+ const above = await resolveFileReferences(
+ [gfsReference({ byteLength: limit + 1 })],
+ client(() => view({ bytes: limit + 1 }))
+ )
+ expect(above).toMatchObject({ ok: true, resolutions: [{ availability: 'too_large' }] })
+ })
+
+ it.each([
+ [403, 'denied'],
+ [404, 'not_found'],
+ [410, 'not_found'],
+ ])('maps gfsc %i to %s', async (status, availability) => {
+ const gfsc = client(() => {
+ throw new GfscHttpError(status, 'no')
+ })
+ const result = await resolveFileReferences([gfsReference()], gfsc)
+ expect(gfsc.resolve).toHaveBeenCalledTimes(1)
+ expect(result).toMatchObject({ ok: true, resolutions: [{ availability }] })
+ })
+
+ it('marks every reference unsupported without calling gfsc when the Host has no read scope', async () => {
+ const refs = [gfsReference(), gfsReference({ resourceId: RID_2 })]
+ const result = await resolveFileReferences(refs, null)
+ expect(result).toEqual({
+ ok: true,
+ resolutions: refs.map(reference => ({ availability: 'unsupported', reference })),
+ })
+ })
+
+ it('marks an attachment-sourced reference unsupported and still resolves the GFS one', async () => {
+ const gfsc = client(() => view())
+ const result = await resolveFileReferences([attachmentReference(), gfsReference()], gfsc)
+ expect(result).toMatchObject({
+ ok: true,
+ resolutions: [{ availability: 'unsupported' }, { availability: 'available' }],
+ })
+ // Witness: only the GFS reference reached gfsc.
+ expect(gfsc.resolve).toHaveBeenCalledTimes(1)
+ })
+
+ it.each([429, 500, 502, 503, 401])('fails transient on gfsc %i', async status => {
+ const gfsc = client(() => {
+ throw new GfscHttpError(status, 'busy')
+ })
+ expect(await resolveFileReferences([gfsReference()], gfsc)).toEqual({
+ ok: false,
+ failure: 'transient',
+ })
+ expect(gfsc.resolve).toHaveBeenCalledTimes(1)
+ })
+
+ it('fails transient on a network error', async () => {
+ const gfsc = client(() => {
+ throw new TypeError('fetch failed')
+ })
+ expect(await resolveFileReferences([gfsReference()], gfsc)).toEqual({
+ ok: false,
+ failure: 'transient',
+ })
+ })
+
+ it('fails invalid on a gfsc 400', async () => {
+ const gfsc = client(() => {
+ throw new GfscHttpError(400, 'path_invalid')
+ })
+ expect(await resolveFileReferences([gfsReference()], gfsc)).toEqual({
+ ok: false,
+ failure: 'invalid',
+ })
+ })
+
+ it('fails invalid when the same version reports a different size', async () => {
+ const gfsc = client(() => view({ bytes: 121 }))
+ expect(await resolveFileReferences([gfsReference()], gfsc)).toEqual({
+ ok: false,
+ failure: 'invalid',
+ })
+ expect(gfsc.resolve).toHaveBeenCalledTimes(1)
+ })
+
+ it.each([
+ ['a non-ok envelope', { ok: false }],
+ ['a text body', 'not json'],
+ ['another drive', view({ drive: 'other' })],
+ ['another resource', view({ resourceId: RID_2, rid: RID_2, gfsUri: `gfs://main/${RID_2}` })],
+ ['another gfsUri', view({ gfsUri: `gfs://main/${RID_2}` })],
+ ['an unknown kind', view({ kind: 'link' })],
+ ['a fractional version', view({ version: 3.5 })],
+ ['a negative size', view({ bytes: -1 })],
+ ])('fails contract on %s', async (_label, body) => {
+ const gfsc = client(() => body)
+ expect(await resolveFileReferences([gfsReference()], gfsc)).toEqual({
+ ok: false,
+ failure: 'contract',
+ })
+ expect(gfsc.resolve).toHaveBeenCalledTimes(1)
+ })
+
+ it('resolves in parallel and aborts the calls still in flight on the first failure', async () => {
+ const signals: AbortSignal[] = []
+ let started = 0
+ const gfsc: FileReferenceGfscClient = {
+ resolve: vi.fn(({ uri }, call) => {
+ started += 1
+ signals.push(call.signal)
+ if (uri.endsWith(RID_2)) return Promise.reject(new GfscHttpError(503, 'down'))
+ return new Promise((_resolve, reject) =>
+ call.signal.addEventListener('abort', () => reject(new Error('aborted')))
+ )
+ }),
+ }
+ const result = await resolveFileReferences(
+ [gfsReference(), gfsReference({ resourceId: RID_2 })],
+ gfsc
+ )
+ expect(result).toEqual({ ok: false, failure: 'transient' })
+ // Witness: both calls started before either finished (one shared signal).
+ expect(started).toBe(2)
+ expect(signals[0]).toBe(signals[1])
+ expect(signals[0]!.aborted).toBe(true)
+ })
+
+ it('fails transient when gfsc does not answer before the deadline', async () => {
+ vi.useFakeTimers()
+ try {
+ let deadlineMs = 0
+ const gfsc: FileReferenceGfscClient = {
+ resolve: vi.fn((_args, call) => {
+ deadlineMs = call.deadlineMs
+ return new Promise((_resolve, reject) =>
+ call.signal.addEventListener('abort', () => reject(new Error('aborted')))
+ )
+ }),
+ }
+ const startedAt = Date.now()
+ const pending = resolveFileReferences([gfsReference()], gfsc)
+ expect(deadlineMs).toBe(startedAt + VISUAL_INPUT_LIMITS.validationTimeoutMs)
+ await vi.advanceTimersByTimeAsync(VISUAL_INPUT_LIMITS.validationTimeoutMs - 1)
+ let settled = false
+ void pending.then(() => {
+ settled = true
+ })
+ await Promise.resolve()
+ expect(settled).toBe(false)
+ await vi.advanceTimersByTimeAsync(1)
+ expect(await pending).toEqual({ ok: false, failure: 'transient' })
+ } finally {
+ vi.useRealTimers()
+ }
+ })
+
+ it('names a code for every unavailable availability', () => {
+ expect(FILE_REFERENCE_AVAILABILITY_CODES).toEqual({
+ not_found: 'FILE_REFERENCE_NOT_FOUND',
+ denied: 'FILE_REFERENCE_DENIED',
+ stale: 'FILE_REFERENCE_STALE',
+ not_a_file: 'FILE_REFERENCE_NOT_A_FILE',
+ too_large: 'FILE_REFERENCE_TOO_LARGE',
+ unsupported: 'FILE_REFERENCE_UNSUPPORTED',
+ })
+ })
+})
+
+describe('referencedFilesForTurnContext (#666)', () => {
+ it('maps each resolution in order, with its code and the current version', () => {
+ const available = gfsReference()
+ const stale = gfsReference({ resourceId: RID_2, version: 1 })
+ const attachment = attachmentReference()
+ expect(
+ referencedFilesForTurnContext([
+ { availability: 'available', reference: available },
+ { availability: 'stale', reference: stale, resolvedVersion: 4 },
+ { availability: 'unsupported', reference: attachment },
+ ])
+ ).toEqual([
+ {
+ referenceId: available.id,
+ name: 'notes.md',
+ class: 'markdown',
+ byteLength: 120,
+ sourceKind: 'gfs',
+ gfs: { drive: 'main', resourceId: RID, version: 3 },
+ availability: 'available',
+ },
+ {
+ referenceId: stale.id,
+ name: 'notes.md',
+ class: 'markdown',
+ byteLength: 120,
+ sourceKind: 'gfs',
+ gfs: { drive: 'main', resourceId: RID_2, version: 1 },
+ availability: 'stale',
+ code: 'FILE_REFERENCE_STALE',
+ currentVersion: 4,
+ },
+ {
+ referenceId: attachment.id,
+ name: 'hello.txt',
+ class: attachment.class,
+ byteLength: 5,
+ sourceKind: 'attachment',
+ availability: 'unsupported',
+ code: 'FILE_REFERENCE_UNSUPPORTED',
+ },
+ ])
+ })
+
+ it('lists nothing for a message without resolutions', () => {
+ // Witness: the same function lists a resolution when one is present.
+ expect(
+ referencedFilesForTurnContext([{ availability: 'denied', reference: gfsReference() }])
+ ).toEqual([expect.objectContaining({ availability: 'denied', code: 'FILE_REFERENCE_DENIED' })])
+ expect(referencedFilesForTurnContext(undefined)).toEqual([])
+ expect(referencedFilesForTurnContext([])).toEqual([])
+ })
+})
diff --git a/mcp-host/src/agent/__tests__/incomingAdmission.fileReferences.test.ts b/mcp-host/src/agent/__tests__/incomingAdmission.fileReferences.test.ts
new file mode 100644
index 000000000..13c2e77b5
--- /dev/null
+++ b/mcp-host/src/agent/__tests__/incomingAdmission.fileReferences.test.ts
@@ -0,0 +1,285 @@
+/**
+ * #666 — admission resolves structured file references before the task exists.
+ * The real resolver runs behind a gfsc double, so every availability here is
+ * the one production would compute.
+ */
+import { type Mock, describe, expect, it, vi } from 'vitest'
+import {
+ type FileReferenceV1,
+ buildGfsFileReference,
+ classifyBytes,
+} from '@clerum/gfs-interaction-policy'
+import { GfscHttpError } from '../../internalTools/gfsClient'
+import type { IncomingMessage, MessageResponse } from '../../server/types'
+import type { FileReferenceGfscClient } from '../fileReferenceResolver'
+import { type IncomingAdmissionDeps, createIncomingAdmission } from '../incomingAdmission'
+
+const RID = '1234567890abcdef1234567890abcdef'
+const RID_2 = 'abcdefabcdefabcdefabcdefabcdefab'
+const FILE_NAME = 'quarterly-SENTINEL-666.md'
+
+function gfsReference(resourceId = RID, version = 3): FileReferenceV1 {
+ const built = buildGfsFileReference({
+ drive: 'main',
+ resourceId,
+ gfsUri: `gfs://main/${resourceId}`,
+ version,
+ name: FILE_NAME,
+ declaredMediaType: 'text/markdown',
+ byteLength: 120,
+ classification: classifyBytes({
+ bytes: new Uint8Array(0),
+ totalByteLength: 120,
+ declaredMediaType: 'text/markdown',
+ filename: FILE_NAME,
+ }),
+ })
+ if (!built.ok) throw new Error(built.message)
+ return built.value
+}
+
+function view(resourceId: string, fields: Record<string, unknown> = {}) {
+ return {
+ ok: true,
+ data: {
+ resourceId,
+ rid: resourceId,
+ drive: 'main',
+ gfsUri: `gfs://main/${resourceId}`,
+ kind: 'file',
+ name: FILE_NAME,
+ version: 3,
+ bytes: 120,
+ ...fields,
+ },
+ }
+}
+
+function message(overrides: Partial<IncomingMessage> = {}): IncomingMessage {
+ return {
+ content: 'summarize the file',
+ channelType: 'rpc',
+ channelId: 'agent-1',
+ sender: 'user-1',
+ timestamp: '2026-09-24T10:00:00Z',
+ messageId: 'msg-1',
+ hostRef: 'host-1',
+ threadId: 'chat-1',
+ ...overrides,
+ }
+}
+
+function makeAdmission(
+ resolve: FileReferenceGfscClient['resolve'] | null,
+ overrides: Partial<IncomingAdmissionDeps> = {}
+) {
+ const order: string[] = []
+ const resolveSpy = resolve
+ ? vi.fn<FileReferenceGfscClient['resolve']>((args, call) => {
+ order.push('resolve')
+ return resolve(args, call)
+ })
+ : null
+ const dispatch = vi.fn<IncomingAdmissionDeps['dispatch']>(() => {
+ order.push('dispatch')
+ return { success: true, taskId: 't-1', status: 'pending' }
+ })
+ const applySessionModelSelection = vi.fn<IncomingAdmissionDeps['applySessionModelSelection']>(
+ async () => {
+ order.push('apply')
+ return { ok: true, provider: 'zai', model: 'glm-5.3-flash', modelSelectionRevision: 2 }
+ }
+ )
+ const info: Mock<IncomingAdmissionDeps['logger']['info']> = vi.fn()
+ const warn: Mock<IncomingAdmissionDeps['logger']['warn']> = vi.fn()
+ const deps: IncomingAdmissionDeps = {
+ limits: { maxCount: 4, maxBytes: 1_000_000, maxFileBytes: 1_000_000 },
+ queueReady: () => true,
+ degradedReason: () => null,
+ hostProvider: () => 'zai',
+ getConversationByKey: async () => undefined,
+ resolveTaskModel: () => null,
+ resolveImageInput: () => undefined,
+ applySessionModelSelection,
+ dispatch,
+ fileReferenceClient: () => (resolveSpy ? { resolve: resolveSpy } : null),
+ logger: { info, warn },
+ ...overrides,
+ }
+ return {
+ admit: createIncomingAdmission(deps),
+ dispatch: deps.dispatch as typeof dispatch,
+ resolve: resolveSpy,
+ applySessionModelSelection,
+ info,
+ warn,
+ order,
+ }
+}
+
+function dispatched(dispatch: Mock<IncomingAdmissionDeps['dispatch']>): IncomingMessage {
+ expect(dispatch).toHaveBeenCalledTimes(1)
+ return dispatch.mock.calls[0]![0]
+}
+
+function events(spy: Mock<(obj: Record<string, unknown>, msg: string) => void>, name: string) {
+ return spy.mock.calls.map(call => call[0]).filter(obj => obj.event === name)
+}
+
+describe('incoming admission with file references (#666)', () => {
+ it('resolves an available reference and names it on the ack', async () => {
+ const ref = gfsReference()
+ const { admit, dispatch, resolve } = makeAdmission(async () => view(RID))
+ const response = await admit(message({ fileReferences: [ref] }))
+ expect(resolve).toHaveBeenCalledTimes(1)
+ expect(dispatched(dispatch).fileReferenceResolutions).toEqual([
+ { availability: 'available', reference: ref },
+ ])
+ expect(response).toEqual({
+ success: true,
+ taskId: 't-1',
+ status: 'pending',
+ acceptedFileReferenceIds: [ref.id],
+ })
+ })
+
+ it('admits unavailable references and lists each with its availability', async () => {
+ const denied = gfsReference()
+ const stale = gfsReference(RID_2)
+ const { admit, dispatch } = makeAdmission(async ({ uri }) => {
+ if (uri.endsWith(RID)) throw new GfscHttpError(403, 'forbidden')
+ return view(RID_2, { version: 5, bytes: 300 })
+ })
+ const response = (await admit(message({ fileReferences: [denied, stale] }))) as MessageResponse
+ expect(dispatched(dispatch).fileReferenceResolutions).toEqual([
+ { availability: 'denied', reference: denied },
+ { availability: 'stale', reference: stale, resolvedVersion: 5 },
+ ])
+ expect(response.acceptedFileReferenceIds).toEqual([denied.id, stale.id])
+ })
+
+ it('marks every reference unsupported, without gfsc, when the Host has no read scope', async () => {
+ const ref = gfsReference()
+ const { admit, dispatch } = makeAdmission(null)
+ const response = (await admit(message({ fileReferences: [ref] }))) as MessageResponse
+ expect(dispatched(dispatch).fileReferenceResolutions).toEqual([
+ { availability: 'unsupported', reference: ref },
+ ])
+ expect(response.acceptedFileReferenceIds).toEqual([ref.id])
+ })
+
+ it('logs classes and availabilities, never the file name', async () => {
+ const { admit, info } = makeAdmission(async () => view(RID))
+ await admit(message({ fileReferences: [gfsReference()] }))
+ const resolved = events(info, 'file_reference_resolved')
+ // Witness: the resolution log line was emitted.
+ expect(resolved).toEqual([
+ expect.objectContaining({
+ referenceCount: 1,
+ availabilities: ['available'],
+ fileClasses: ['markdown'],
+ byteLength: 120,
+ }),
+ ])
+ expect(JSON.stringify(info.mock.calls)).not.toContain('SENTINEL-666')
+ })
+
+ it.each([
+ [
+ 'a transient gfsc failure',
+ () => Promise.reject(new GfscHttpError(503, 'not_mounted')),
+ { code: 'LLM_API_CALL_FAILED', retryable: true },
+ 'transient',
+ ],
+ [
+ 'a gfsc 400',
+ () => Promise.reject(new GfscHttpError(400, 'path_invalid')),
+ { code: 'FILE_REFERENCE_INVALID', retryable: false },
+ 'invalid',
+ ],
+ [
+ 'metadata about another file',
+ () => Promise.resolve(view(RID_2)),
+ { code: 'LLM_API_CALL_FAILED', retryable: false },
+ 'contract',
+ ],
+ ])('refuses the message on %s', async (_label, answer, error, failure) => {
+ const { admit, dispatch, resolve, warn } = makeAdmission(answer)
+ const response = await admit(message({ fileReferences: [gfsReference()] }))
+ expect(response).toEqual({
+ success: false,
+ error: { ...error, message: expect.any(String), provider: 'zai' },
+ })
+ // Witness: gfsc was asked, and the refusal was logged with its failure.
+ expect(resolve).toHaveBeenCalledTimes(1)
+ expect(events(warn, 'file_reference_refused')).toEqual([
+ expect.objectContaining({ referenceCount: 1, failure }),
+ ])
+ expect(dispatch).not.toHaveBeenCalled()
+ })
+
+ it('resolves before the piggybacked model write, and skips the write on a refusal', async () => {
+ const ok = makeAdmission(async () => view(RID))
+ const response = (await ok.admit(
+ message({ fileReferences: [gfsReference()], model: 'glm-5.3-flash' })
+ )) as MessageResponse
+ expect(ok.order).toEqual(['resolve', 'apply', 'dispatch'])
+ expect(response).toMatchObject({
+ modelSelectionRevision: 2,
+ acceptedFileReferenceIds: [gfsReference().id],
+ })
+
+ const refused = makeAdmission(() => Promise.reject(new GfscHttpError(503, 'down')))
+ await refused.admit(message({ fileReferences: [gfsReference()], model: 'glm-5.3-flash' }))
+ expect(refused.order).toEqual(['resolve'])
+ expect(refused.applySessionModelSelection).not.toHaveBeenCalled()
+ })
+
+ it('never forwards caller-supplied resolutions', async () => {
+ const forged = [{ availability: 'available' as const, reference: gfsReference() }]
+ const { admit, dispatch, resolve } = makeAdmission(async () => view(RID))
+ const response = (await admit(message({ fileReferenceResolutions: forged }))) as MessageResponse
+ expect(dispatched(dispatch).fileReferenceResolutions).toBeUndefined()
+ expect(resolve).not.toHaveBeenCalled()
+ expect(response).toEqual({ success: true, taskId: 't-1', status: 'pending' })
+ })
+
+ it('omits the ids when dispatch refuses the task', async () => {
+ const { admit, dispatch, resolve } = makeAdmission(async () => view(RID), {
+ dispatch: vi.fn(() => ({
+ success: false,
+ error: { code: 'X', message: 'no', retryable: false, provider: 'zai' },
+ })),
+ })
+ const response = await admit(message({ fileReferences: [gfsReference()] }))
+ // Witness: the reference was resolved and the resolved message dispatched.
+ expect(resolve).toHaveBeenCalledTimes(1)
+ expect(dispatched(dispatch).fileReferenceResolutions).toHaveLength(1)
+ expect(response).not.toHaveProperty('acceptedFileReferenceIds')
+ expect(response).toMatchObject({ success: false })
+ })
+
+ it('names the ids on an async ack', async () => {
+ const ref = gfsReference()
+ const { admit } = makeAdmission(async () => view(RID), {
+ dispatch: vi.fn(async () => ({ success: true, taskId: 't-9', status: 'pending' as const })),
+ })
+ expect(await admit(message({ fileReferences: [ref] }), { async: true })).toEqual({
+ success: true,
+ taskId: 't-9',
+ status: 'pending',
+ acceptedFileReferenceIds: [ref.id],
+ })
+ })
+
+ it('does not call gfsc when the queue is not ready', async () => {
+ const { admit, resolve, dispatch } = makeAdmission(async () => view(RID), {
+ queueReady: () => false,
+ })
+ const response = await admit(message({ fileReferences: [gfsReference()] }))
+ // Witness: the queue gate produced its own refusal.
+ expect(response).toMatchObject({ error: { message: 'Message queue not initialized' } })
+ expect(resolve).not.toHaveBeenCalled()
+ expect(dispatch).not.toHaveBeenCalled()
+ })
+})
diff --git a/mcp-host/src/agent/__tests__/incomingAdmission.modelSelection.test.ts b/mcp-host/src/agent/__tests__/incomingAdmission.modelSelection.test.ts
index fde740772..83230e48c 100644
--- a/mcp-host/src/agent/__tests__/incomingAdmission.modelSelection.test.ts
+++ b/mcp-host/src/agent/__tests__/incomingAdmission.modelSelection.test.ts
@@ -129,6 +129,7 @@ describe('image sends and the session model selection', () => {
resolveImageInput,
applySessionModelSelection: applySelection,
dispatch,
+ fileReferenceClient: () => null,
logger: { info: vi.fn(), warn: vi.fn() },
})
})
diff --git a/mcp-host/src/agent/__tests__/incomingAdmission.test.ts b/mcp-host/src/agent/__tests__/incomingAdmission.test.ts
index b78152c3d..27ee143df 100644
--- a/mcp-host/src/agent/__tests__/incomingAdmission.test.ts
+++ b/mcp-host/src/agent/__tests__/incomingAdmission.test.ts
@@ -90,6 +90,7 @@ function makeAdmission(overrides: Partial<IncomingAdmissionDeps> = {}): {
taskId: 't-1',
status: 'pending',
})),
+ fileReferenceClient: () => null,
logger,
...overrides,
}
diff --git a/mcp-host/src/agent/fileReferenceResolver.ts b/mcp-host/src/agent/fileReferenceResolver.ts
new file mode 100644
index 000000000..8be39aff7
--- /dev/null
+++ b/mcp-host/src/agent/fileReferenceResolver.ts
@@ -0,0 +1,240 @@
+/**
+ * Issue #666 — structured file references on an incoming message.
+ *
+ * `parseIncomingFileReferences` is the route-level contract check: shape,
+ * count, uniqueness and GFS identity, with no I/O. `resolveFileReferences`
+ * re-authorizes every GFS reference under the Host principal with gfsc
+ * `resolve` (JSON metadata only, never bytes) and reports one availability per
+ * reference. The model reads an available file later with `clerum__gfs_read`
+ * and the reference's version as `expectedVersion`.
+ */
+import { type FileReferenceV1, parseFileReferenceV1 } from '@clerum/gfs-interaction-policy'
+import { FileReferenceErrorCode } from '../core/errors'
+import type { TurnContextReferencedFile } from '../core/orchestration/turnContext'
+import { GfscHttpError } from '../internalTools/gfsClient'
+import { VISUAL_INPUT_LIMITS } from '../visualInput/policy'
+
+export type FileReferenceAvailability =
+ | 'available'
+ | 'not_found'
+ | 'denied'
+ | 'stale'
+ | 'not_a_file'
+ | 'too_large'
+ | 'unsupported'
+
+export interface FileReferenceResolution {
+ availability: FileReferenceAvailability
+ reference: FileReferenceV1
+ /** The version gfsc reports now, when it differs from the reference's. */
+ resolvedVersion?: number
+}
+
+/** The code each unavailable reference is reported under (log and turn block). */
+export const FILE_REFERENCE_AVAILABILITY_CODES: Record<
+ Exclude<FileReferenceAvailability, 'available'>,
+ FileReferenceErrorCode
+> = {
+ not_found: FileReferenceErrorCode.NotFound,
+ denied: FileReferenceErrorCode.Denied,
+ stale: FileReferenceErrorCode.Stale,
+ not_a_file: FileReferenceErrorCode.NotAFile,
+ too_large: FileReferenceErrorCode.TooLarge,
+ unsupported: FileReferenceErrorCode.Unsupported,
+}
+
+/** The `referenced_file` entries for the turn-context block, in message order. */
+export function referencedFilesForTurnContext(
+ resolutions: readonly FileReferenceResolution[] | undefined
+): TurnContextReferencedFile[] {
+ return (resolutions ?? []).map(({ availability, reference, resolvedVersion }) => {
+ const { source } = reference
+ return {
+ referenceId: reference.id,
+ name: reference.name,
+ class: reference.class,
+ byteLength: reference.byteLength,
+ sourceKind: source.kind,
+ ...(source.kind === 'gfs'
+ ? { gfs: { drive: source.drive, resourceId: source.resourceId, version: source.version } }
+ : {}),
+ availability,
+ ...(availability === 'available'
+ ? {}
+ : { code: FILE_REFERENCE_AVAILABILITY_CODES[availability] }),
+ ...(resolvedVersion === undefined ? {} : { currentVersion: resolvedVersion }),
+ }
+ })
+}
+
+export type ParsedIncomingFileReferences =
+ | { ok: true; references: FileReferenceV1[] }
+ | {
+ ok: false
+ code: FileReferenceErrorCode.SchemaVersionUnsupported | FileReferenceErrorCode.Invalid
+ message: string
+ }
+
+function normalizeRid(value: string): string | null {
+ const normalized = value.replace(/-/g, '').toLowerCase()
+ return /^[a-f0-9]{32}$/.test(normalized) ? normalized : null
+}
+
+/** `undefined` is a message without references; anything else must be a list. */
+export function parseIncomingFileReferences(
+ value: unknown,
+ maxCount: number
+): ParsedIncomingFileReferences {
+ if (value === undefined) return { ok: true, references: [] }
+ const invalid = (message: string): ParsedIncomingFileReferences => ({
+ ok: false,
+ code: FileReferenceErrorCode.Invalid,
+ message,
+ })
+ if (!Array.isArray(value)) return invalid('fileReferences must be a list.')
+ if (value.length > maxCount) return invalid(`A message can reference at most ${maxCount} files.`)
+ const references: FileReferenceV1[] = []
+ const ids = new Set<string>()
+ for (const entry of value) {
+ const parsed = parseFileReferenceV1(entry)
+ if (!parsed.ok) {
+ return {
+ ok: false,
+ code:
+ parsed.code === 'FILE_REFERENCE_SCHEMA_VERSION_UNSUPPORTED'
+ ? FileReferenceErrorCode.SchemaVersionUnsupported
+ : FileReferenceErrorCode.Invalid,
+ message: parsed.message,
+ }
+ }
+ const reference = parsed.value
+ if (ids.has(reference.id)) return invalid('Each file reference must appear once.')
+ ids.add(reference.id)
+ if (reference.source.kind === 'gfs') {
+ const rid = normalizeRid(reference.source.resourceId)
+ if (!rid || reference.source.gfsUri !== `gfs://${reference.source.drive}/${rid}`)
+ return invalid('The gfsUri of a file reference must name its drive and resourceId.')
+ }
+ references.push(reference)
+ }
+ return { ok: true, references }
+}
+
+/** The gfsc surface resolution needs: one JSON metadata call. */
+export interface FileReferenceGfscClient {
+ resolve(
+ args: { uri: string },
+ call: { signal: AbortSignal; deadlineMs: number }
+ ): Promise<unknown>
+}
+
+export type FileReferenceResolutionResult =
+ | { ok: true; resolutions: FileReferenceResolution[] }
+ /** gfsc was unavailable, slow or rate-limited: the client may resend. */
+ | { ok: false; failure: 'transient' }
+ /** gfsc refused the reference as malformed, or it misstates the file's size. */
+ | { ok: false; failure: 'invalid' }
+ /** gfsc answered 200 with metadata that is not about the referenced file. */
+ | { ok: false; failure: 'contract' }
+
+class ResolutionFailure extends Error {
+ constructor(readonly failure: 'transient' | 'invalid' | 'contract') {
+ super(`file reference resolution failed: ${failure}`)
+ this.name = 'ResolutionFailure'
+ }
+}
+
+interface ResolvedView {
+ kind: 'file' | 'directory'
+ version: number
+ bytes: number
+}
+
+function resolvedView(
+ body: unknown,
+ source: Extract<FileReferenceV1['source'], { kind: 'gfs' }>
+): ResolvedView {
+ const envelope = body as { ok?: unknown; data?: unknown } | null
+ if (
+ !envelope ||
+ typeof envelope !== 'object' ||
+ envelope.ok !== true ||
+ !envelope.data ||
+ typeof envelope.data !== 'object'
+ )
+ throw new ResolutionFailure('contract')
+ const data = envelope.data as Record<string, unknown>
+ const rid = normalizeRid(source.resourceId)
+ if (
+ typeof data.resourceId !== 'string' ||
+ normalizeRid(data.resourceId) !== rid ||
+ data.rid !== rid ||
+ data.drive !== source.drive ||
+ data.gfsUri !== source.gfsUri ||
+ (data.kind !== 'file' && data.kind !== 'directory') ||
+ !Number.isSafeInteger(data.version) ||
+ (data.version as number) < 0 ||
+ !Number.isSafeInteger(data.bytes) ||
+ (data.bytes as number) < 0
+ )
+ throw new ResolutionFailure('contract')
+ return { kind: data.kind, version: data.version as number, bytes: data.bytes as number }
+}
+
+async function resolveOne(
+ reference: FileReferenceV1,
+ client: FileReferenceGfscClient | null,
+ call: { signal: AbortSignal; deadlineMs: number }
+): Promise<FileReferenceResolution> {
+ const source = reference.source
+ if (source.kind !== 'gfs' || !client) return { availability: 'unsupported', reference }
+ let body: unknown
+ try {
+ body = await client.resolve({ uri: source.gfsUri }, call)
+ } catch (error) {
+ if (error instanceof GfscHttpError) {
+ // gfsc checks the grant before the lookup, so a missing resource usually
+ // answers 403 too; 404/410 only reach a principal that could read it.
+ if (error.status === 403) return { availability: 'denied', reference }
+ if (error.status === 404 || error.status === 410)
+ return { availability: 'not_found', reference }
+ if (error.status === 400) throw new ResolutionFailure('invalid')
+ }
+ throw new ResolutionFailure('transient')
+ }
+ const view = resolvedView(body, source)
+ if (view.kind === 'directory') return { availability: 'not_a_file', reference }
+ if (view.version !== source.version)
+ return { availability: 'stale', reference, resolvedVersion: view.version }
+ // Same version, so the same bytes: a different size is a reference that
+ // misstates the file, not a change to it.
+ if (view.bytes !== reference.byteLength) throw new ResolutionFailure('invalid')
+ if (view.bytes > VISUAL_INPUT_LIMITS.fileBytes) return { availability: 'too_large', reference }
+ return { availability: 'available', reference }
+}
+
+/**
+ * Resolves every reference in parallel under one deadline. The first failure
+ * aborts the calls still in flight.
+ */
+export async function resolveFileReferences(
+ references: readonly FileReferenceV1[],
+ client: FileReferenceGfscClient | null,
+ timeoutMs: number = VISUAL_INPUT_LIMITS.validationTimeoutMs
+): Promise<FileReferenceResolutionResult> {
+ const controller = new AbortController()
+ const timer = setTimeout(() => controller.abort(), timeoutMs)
+ const call = { signal: controller.signal, deadlineMs: Date.now() + timeoutMs }
+ try {
+ const resolutions = await Promise.all(
+ references.map(reference => resolveOne(reference, client, call))
+ )
+ return { ok: true, resolutions }
+ } catch (error) {
+ if (error instanceof ResolutionFailure) return { ok: false, failure: error.failure }
+ throw error
+ } finally {
+ clearTimeout(timer)
+ controller.abort()
+ }
+}
diff --git a/mcp-host/src/agent/incomingAdmission.ts b/mcp-host/src/agent/incomingAdmission.ts
index f1eae1126..705769815 100644
--- a/mcp-host/src/agent/incomingAdmission.ts
+++ b/mcp-host/src/agent/incomingAdmission.ts
@@ -9,14 +9,16 @@
* from live process state arrives through {@link IncomingAdmissionDeps}; the
* decision logic here is pure.
*/
-import { LlmErrorCode } from '../core/errors'
+import { FileReferenceErrorCode, LlmErrorCode } from '../core/errors'
import {
chatTransportSupportsImageInput,
imageInputDenialMessage,
resolveHostImageInput,
} from '../llm/imageInput'
+import type { TaskError } from '../queue/types'
import type { IncomingMessage, MessageResponse, SetModelResult } from '../server/types'
import { serializeSessionKey } from '../session/types.js'
+import { type FileReferenceGfscClient, resolveFileReferences } from './fileReferenceResolver'
import { type IncomingAttachmentLimits, validateIncomingAttachments } from './incomingAttachments'
import type { SessionModelSelectionOptions } from './sessionModelSelection'
@@ -62,6 +64,12 @@ export interface IncomingAdmissionDeps {
message: IncomingMessage,
options?: { async?: boolean }
) => MessageResponse | Promise<MessageResponse>
+ /**
+ * Issue #666 — the gfsc client that re-authorizes file references, or null
+ * when this Host holds no `gfs.read` scope (every GFS reference is then
+ * `unsupported`, and gfsc is never called).
+ */
+ fileReferenceClient: () => FileReferenceGfscClient | null
logger: {
info: (obj: Record<string, unknown>, msg: string) => void
warn: (obj: Record<string, unknown>, msg: string) => void
@@ -139,7 +147,11 @@ export function createIncomingAdmission(deps: IncomingAdmissionDeps): IncomingAd
attachments: validated.attachments,
// Never accept a caller-supplied visual execution identity.
imageModel: undefined,
+ // Resolutions are the Host's own answer; a caller cannot pre-fill them.
+ fileReferenceResolutions: undefined,
}
+ const fileReferences = message.fileReferences ?? []
+ let acceptedFileReferenceIds: string[] = []
deps.logger.info(
{
channel: normalizedMessage.channelType,
@@ -192,12 +204,17 @@ export function createIncomingAdmission(deps: IncomingAdmissionDeps): IncomingAd
}
}
- // A successful response names every attachment the Host accepted, on the
- // sync response and on the async ack alike. Its absence on a send that
- // carried attachments is how a client detects a Host that dropped them.
+ // A successful response names every attachment and file reference the Host
+ // accepted, on the sync response and on the async ack alike. Their absence
+ // on a send that carried them is how a client detects a Host that dropped
+ // them.
const withAcceptedAttachments = (response: MessageResponse): MessageResponse =>
- response.success && acceptedAttachmentIds.length
- ? { ...response, acceptedAttachmentIds }
+ response.success && (acceptedAttachmentIds.length || acceptedFileReferenceIds.length)
+ ? {
+ ...response,
+ ...(acceptedAttachmentIds.length ? { acceptedAttachmentIds } : {}),
+ ...(acceptedFileReferenceIds.length ? { acceptedFileReferenceIds } : {}),
+ }
: response
const dispatchMessage = (): MessageResponse | Promise<MessageResponse> => {
const response = deps.dispatch(normalizedMessage, options)
@@ -294,69 +311,108 @@ export function createIncomingAdmission(deps: IncomingAdmissionDeps): IncomingAd
// `conv.modelSelections`) reads the row we just wrote. Fail-OPEN on the
// message: a rejected/degraded selection is logged and ignored, never dropping
// the user's turn (fail-closed only on the selection, inside the helper).
- const piggybackModel = typeof message.model === 'string' ? message.model.trim() : ''
- if (piggybackModel && normalizedMessage.channelType === 'rpc') {
- // An image the requested model cannot read is refused BEFORE the
- // selection is written: persisting it (and bumping the revision) for a
- // turn that is then refused would leave the session on a model the user
- // never got an answer from. Only the pair the selection resolves to is
- // checked here; when resolution does not honour the requested model
- // (not in the catalog, or a boot fallback serves another pair) the write
- // gate and the per-task check below keep their existing verdicts.
- const hostProvider = deps.hostProvider()
- if (hasImageAttachments && hostProvider) {
- const requested = deps.resolveTaskModel({ [hostProvider]: piggybackModel })
- if (
- !requested ||
- (requested.provider.getProviderType() === hostProvider &&
- requested.model === piggybackModel)
- ) {
- const admission = admitImageModel(requested)
- if (!admission.ok) return admission.response
+ const admitAndRun = (): MessageResponse | Promise<MessageResponse> => {
+ const piggybackModel = typeof message.model === 'string' ? message.model.trim() : ''
+ if (piggybackModel && normalizedMessage.channelType === 'rpc') {
+ // An image the requested model cannot read is refused BEFORE the
+ // selection is written: persisting it (and bumping the revision) for a
+ // turn that is then refused would leave the session on a model the user
+ // never got an answer from. Only the pair the selection resolves to is
+ // checked here; when resolution does not honour the requested model
+ // (not in the catalog, or a boot fallback serves another pair) the write
+ // gate and the per-task check below keep their existing verdicts.
+ const hostProvider = deps.hostProvider()
+ if (hasImageAttachments && hostProvider) {
+ const requested = deps.resolveTaskModel({ [hostProvider]: piggybackModel })
+ if (
+ !requested ||
+ (requested.provider.getProviderType() === hostProvider &&
+ requested.model === piggybackModel)
+ ) {
+ const admission = admitImageModel(requested)
+ if (!admission.ok) return admission.response
+ }
}
- }
- return (async () => {
- // Hoisted out of the try so the ack below can report the revision the
- // write produced. The send IS the write; its result travels back here.
- let applied: SetModelResult | undefined
- try {
- applied = await deps.applySessionModelSelection(
- normalizedMessage.sender,
- normalizedMessage.channelId,
- normalizedMessage.threadId,
- piggybackModel,
- hasImageAttachments ? message.modelSelectionRevision : undefined,
- // An image send carries the model the client displays, not a user
- // pick: asking for the effective model must not pin it. Text-only
- // piggybacks and `POST /v1/runtime/model` keep writing.
- hasImageAttachments ? { skipWriteWhenEffective: true } : undefined
- )
- if (!applied.ok) {
+ return (async () => {
+ // Hoisted out of the try so the ack below can report the revision the
+ // write produced. The send IS the write; its result travels back here.
+ let applied: SetModelResult | undefined
+ try {
+ applied = await deps.applySessionModelSelection(
+ normalizedMessage.sender,
+ normalizedMessage.channelId,
+ normalizedMessage.threadId,
+ piggybackModel,
+ hasImageAttachments ? message.modelSelectionRevision : undefined,
+ // An image send carries the model the client displays, not a user
+ // pick: asking for the effective model must not pin it. Text-only
+ // piggybacks and `POST /v1/runtime/model` keep writing.
+ hasImageAttachments ? { skipWriteWhenEffective: true } : undefined
+ )
+ if (!applied.ok) {
+ if (hasImageAttachments) {
+ const conflict = applied.reason === 'model_selection_conflict'
+ const code = conflict
+ ? LlmErrorCode.ModelSelectionConflict
+ : LlmErrorCode.ModelNotAllowed
+ logRefusal({
+ provider: applied.provider,
+ model: applied.model,
+ code,
+ reason: applied.reason,
+ })
+ return {
+ success: false,
+ // The winning revision, so the client can adopt it and retry
+ // without a separate read against a Host that may suspend again.
+ ...(conflict && applied.modelSelectionRevision !== undefined
+ ? { modelSelectionRevision: applied.modelSelectionRevision }
+ : {}),
+ error: {
+ code,
+ message: conflict
+ ? 'The model selection changed before this message was accepted. Select the model again.'
+ : 'The selected model is no longer allowed. Select a model again before sending the image.',
+ retryable: conflict,
+ provider: applied.provider,
+ },
+ }
+ }
+ deps.logger.warn(
+ {
+ level: 'warn',
+ event: 'message_model_ignored',
+ userId: normalizedMessage.sender,
+ chatId: normalizedMessage.threadId ?? null,
+ provider: applied.provider,
+ model: piggybackModel,
+ reason: applied.reason,
+ },
+ 'Host runtime event'
+ )
+ } else if (hasImageAttachments) {
+ acceptedVisualSelection = { [applied.provider]: applied.model }
+ }
+ } catch (error) {
+ applied = undefined
if (hasImageAttachments) {
- const conflict = applied.reason === 'model_selection_conflict'
- const code = conflict
- ? LlmErrorCode.ModelSelectionConflict
- : LlmErrorCode.ModelNotAllowed
+ deps.logger.warn({ err: error }, 'Visual model selection could not be confirmed')
logRefusal({
- provider: applied.provider,
- model: applied.model,
- code,
- reason: applied.reason,
+ provider: deps.hostProvider() ?? 'unknown',
+ model: piggybackModel,
+ code: LlmErrorCode.ApiCallFailed,
+ reason: 'apply_failed',
})
+ // An unreachable selection store is an internal failure, not a
+ // statement about what this model can accept: the client may retry.
return {
success: false,
- // The winning revision, so the client can adopt it and retry
- // without a separate read against a Host that may suspend again.
- ...(conflict && applied.modelSelectionRevision !== undefined
- ? { modelSelectionRevision: applied.modelSelectionRevision }
- : {}),
error: {
- code,
- message: conflict
- ? 'The model selection changed before this message was accepted. Select the model again.'
- : 'The selected model is no longer allowed. Select a model again before sending the image.',
- retryable: conflict,
- provider: applied.provider,
+ code: LlmErrorCode.ApiCallFailed,
+ message:
+ 'The image model selection could not be confirmed. Select the model again.',
+ retryable: true,
+ provider: deps.hostProvider() ?? 'unknown',
},
}
}
@@ -366,62 +422,80 @@ export function createIncomingAdmission(deps: IncomingAdmissionDeps): IncomingAd
event: 'message_model_ignored',
userId: normalizedMessage.sender,
chatId: normalizedMessage.threadId ?? null,
- provider: applied.provider,
+ provider: deps.hostProvider() ?? 'unknown',
model: piggybackModel,
- reason: applied.reason,
+ reason: 'apply_failed',
+ err: error,
},
'Host runtime event'
)
- } else if (hasImageAttachments) {
- acceptedVisualSelection = { [applied.provider]: applied.model }
}
- } catch (error) {
- applied = undefined
- if (hasImageAttachments) {
- deps.logger.warn({ err: error }, 'Visual model selection could not be confirmed')
- logRefusal({
- provider: deps.hostProvider() ?? 'unknown',
- model: piggybackModel,
- code: LlmErrorCode.ApiCallFailed,
- reason: 'apply_failed',
- })
- // An unreachable selection store is an internal failure, not a
- // statement about what this model can accept: the client may retry.
- return {
- success: false,
- error: {
- code: LlmErrorCode.ApiCallFailed,
- message:
- 'The image model selection could not be confirmed. Select the model again.',
- retryable: true,
- provider: deps.hostProvider() ?? 'unknown',
- },
- }
- }
- deps.logger.warn(
- {
- level: 'warn',
- event: 'message_model_ignored',
- userId: normalizedMessage.sender,
- chatId: normalizedMessage.threadId ?? null,
- provider: deps.hostProvider() ?? 'unknown',
- model: piggybackModel,
- reason: 'apply_failed',
- err: error,
- },
- 'Host runtime event'
- )
- }
- const response = await runHandler()
- // A successful ack carries the revision only when the selection was
- // actually persisted. Its ABSENCE after a piggyback is the contract for
- // "the Host ignored your model".
- return applied?.ok && applied.modelSelectionRevision !== undefined
- ? { ...response, modelSelectionRevision: applied.modelSelectionRevision }
- : response
- })()
+ const response = await runHandler()
+ // A successful ack carries the revision only when the selection was
+ // actually persisted. Its ABSENCE after a piggyback is the contract for
+ // "the Host ignored your model".
+ return applied?.ok && applied.modelSelectionRevision !== undefined
+ ? { ...response, modelSelectionRevision: applied.modelSelectionRevision }
+ : response
+ })()
+ }
+
+ return runHandler()
}
- return runHandler()
+ if (!fileReferences.length) return admitAndRun()
+ // Issue #666 — every reference is re-authorized under the Host principal
+ // before the task exists. An unavailable file is still a valid turn: it is
+ // listed with its availability. Only a failure to ask gfsc refuses it.
+ return (async () => {
+ const resolved = await resolveFileReferences(fileReferences, deps.fileReferenceClient())
+ if (!resolved.ok) {
+ deps.logger.warn(
+ {
+ event: 'file_reference_refused',
+ channel: normalizedMessage.channelType,
+ referenceCount: fileReferences.length,
+ failure: resolved.failure,
+ },
+ 'Host runtime event'
+ )
+ return { success: false, error: fileReferenceFailure(resolved.failure) }
+ }
+ normalizedMessage.fileReferenceResolutions = resolved.resolutions
+ acceptedFileReferenceIds = resolved.resolutions.map(r => r.reference.id)
+ // Classes, sizes and availabilities only: never a file name.
+ deps.logger.info(
+ {
+ event: 'file_reference_resolved',
+ channel: normalizedMessage.channelType,
+ referenceCount: resolved.resolutions.length,
+ fileClasses: resolved.resolutions.map(r => r.reference.class),
+ availabilities: resolved.resolutions.map(r => r.availability),
+ byteLength: resolved.resolutions.reduce((sum, r) => sum + r.reference.byteLength, 0),
+ },
+ 'Host runtime event'
+ )
+ return admitAndRun()
+ })()
+
+ function fileReferenceFailure(failure: 'transient' | 'invalid' | 'contract'): TaskError {
+ const provider = deps.hostProvider() ?? 'unknown'
+ if (failure === 'invalid')
+ return {
+ code: FileReferenceErrorCode.Invalid,
+ message: 'A referenced file does not match the file it names. Pick the file again.',
+ retryable: false,
+ provider,
+ }
+ return {
+ code: LlmErrorCode.ApiCallFailed,
+ message:
+ failure === 'transient'
+ ? 'The referenced files could not be checked. Send the message again.'
+ : 'The file service returned an unexpected answer for a referenced file.',
+ retryable: failure === 'transient',
+ provider,
+ }
+ }
}
}
diff --git a/mcp-host/src/agent/taskExecutor.ts b/mcp-host/src/agent/taskExecutor.ts
index 2767217d1..5b8133240 100644
--- a/mcp-host/src/agent/taskExecutor.ts
+++ b/mcp-host/src/agent/taskExecutor.ts
@@ -114,6 +114,7 @@ import { GovernedRunReporter, UsageReporter } from '../usage/usageReporter.js'
import { resolveProviderWorkflowCallerContext } from '../workflow/providerWorkflowCallerContextClient'
import type { Workspace } from '../workspace/service'
import type { CronScheduler } from './cronScheduler'
+import { referencedFilesForTurnContext } from './fileReferenceResolver'
import {
type ProviderWorkflowAccessDenialReason,
isProviderWorkflowChannel,
@@ -1094,12 +1095,14 @@ export class TaskExecutor {
// prompt and into a `<turn-context>` block prepended to the LAST user
// message of the turn. Only the first user message of the turn gets it;
// `tool` messages keep their content untouched.
- // #666 — the block is also the only carrier of the `attached_file` lines,
- // so a message with file attachments gets it with the cache off too; the
- // same condition registers `clerum__attachment_read`.
+ // #666 — the block is also the only carrier of the `attached_file` and
+ // `referenced_file` lines, so a message with file attachments or resolved
+ // file references gets it with the cache off too; the attachment
+ // condition also registers `clerum__attachment_read`.
const hasFileAttachments =
this.task.sourceMessage?.attachments?.some(attachment => attachment.kind === 'file') === true
- if (appConfig.promptCacheEnabled || hasFileAttachments) {
+ const hasFileReferences = (this.task.sourceMessage?.fileReferenceResolutions?.length ?? 0) > 0
+ if (appConfig.promptCacheEnabled || hasFileAttachments || hasFileReferences) {
this.prependTurnContextBlock(messages)
}
const promptAssemblyStart = Date.now()
@@ -1141,6 +1144,9 @@ export class TaskExecutor {
}
: undefined,
attachedFiles: attachedFilesForTurnContext(this.task.sourceMessage?.attachments),
+ referencedFiles: referencedFilesForTurnContext(
+ this.task.sourceMessage?.fileReferenceResolutions
+ ),
})
const isCron = this.task.cronJobId !== undefined
if (m.contentParts && m.contentParts.length > 0) {
diff --git a/mcp-host/src/config.ts b/mcp-host/src/config.ts
index 64cdf3883..21e0573fe 100644
--- a/mcp-host/src/config.ts
+++ b/mcp-host/src/config.ts
@@ -236,6 +236,8 @@ export interface Config {
attachmentFileMaxBytes: number
/** Bytes one `clerum__attachment_read` call may return (issue #666). */
attachmentTextReadMaxBytes: number
+ /** Structured file references one incoming message may carry (issue #666). */
+ fileReferenceMaxCount: number
activityBufferSize: number
activityMaxEventBytes: number
@@ -972,6 +974,7 @@ export const config: Config = {
attachmentMaxBytes: parseInt(getEnv('CLERUM_ATTACHMENT_MAX_BYTES', '52428800')!, 10),
attachmentFileMaxBytes: getExecutionLimit('CLERUM_ATTACHMENT_FILE_MAX_BYTES', 3_145_728),
attachmentTextReadMaxBytes,
+ fileReferenceMaxCount: getExecutionLimit('CLERUM_FILE_REFERENCE_MAX_COUNT', 10),
activityBufferSize: parseInt(getEnv('MCP_HOST_ACTIVITY_BUFFER_SIZE', '1000')!, 10),
activityMaxEventBytes: parseInt(getEnv('MCP_HOST_ACTIVITY_MAX_EVENT_BYTES', '2048')!, 10),
diff --git a/mcp-host/src/core/errors.ts b/mcp-host/src/core/errors.ts
index ed002b79e..af1d4cc5b 100644
--- a/mcp-host/src/core/errors.ts
+++ b/mcp-host/src/core/errors.ts
@@ -84,6 +84,27 @@ export enum FileAttachmentErrorCode {
DigestMismatch = 'FILE_ATTACHMENT_DIGEST_MISMATCH',
}
+/**
+ * Issue #666 — structured file references on an incoming message.
+ * `SchemaVersionUnsupported` and `Invalid` reject the message (terminal). The
+ * remaining codes name an availability the Host resolved; the message is still
+ * admitted and the reference is listed with that availability in the turn.
+ */
+export enum FileReferenceErrorCode {
+ /** The reference declares a `schemaVersion` this Host does not implement. */
+ SchemaVersionUnsupported = 'FILE_REFERENCE_SCHEMA_VERSION_UNSUPPORTED',
+ /** Shape, count or GFS identity of the reference is invalid. */
+ Invalid = 'FILE_REFERENCE_INVALID',
+ NotFound = 'FILE_REFERENCE_NOT_FOUND',
+ Denied = 'FILE_REFERENCE_DENIED',
+ /** The file changed since the reference was taken. */
+ Stale = 'FILE_REFERENCE_STALE',
+ NotAFile = 'FILE_REFERENCE_NOT_A_FILE',
+ TooLarge = 'FILE_REFERENCE_TOO_LARGE',
+ /** The Host cannot serve this reference (no `gfs.read` scope, or not a GFS source). */
+ Unsupported = 'FILE_REFERENCE_UNSUPPORTED',
+}
+
export class LlmError extends AgentError {
constructor(
message: string,
diff --git a/mcp-host/src/core/orchestration/__tests__/turnContext.test.ts b/mcp-host/src/core/orchestration/__tests__/turnContext.test.ts
index d7bef93ef..f9d372a72 100644
--- a/mcp-host/src/core/orchestration/__tests__/turnContext.test.ts
+++ b/mcp-host/src/core/orchestration/__tests__/turnContext.test.ts
@@ -3,7 +3,9 @@ import type { FileReferenceV1 } from '@clerum/gfs-interaction-policy'
import type { Attachment } from '../../types'
import {
ATTACHED_FILES_INSTRUCTION,
+ REFERENCED_FILES_INSTRUCTION,
type TurnContextAttachedFile,
+ type TurnContextReferencedFile,
attachedFilesForTurnContext,
buildTurnContextBlock,
} from '../turnContext'
@@ -203,3 +205,106 @@ describe('attachedFilesForTurnContext (issue #666)', () => {
expect(attachedFilesForTurnContext(undefined)).toEqual([])
})
})
+
+describe('referenced_file lines (issue #666)', () => {
+ const date = new Date('2026-05-19T14:30:00Z')
+ const available: TurnContextReferencedFile = {
+ referenceId: 'gfs:main:0000000000000000000000000000000a@v3',
+ name: 'plan.md',
+ class: 'markdown',
+ byteLength: 120,
+ sourceKind: 'gfs',
+ gfs: { drive: 'main', resourceId: '0000000000000000000000000000000a', version: 3 },
+ availability: 'available',
+ }
+
+ it('lists each reference with its availability, followed by the fixed instruction', () => {
+ const block = buildTurnContextBlock({
+ date,
+ channel: { type: 'rpc', sender: 'jose' },
+ referencedFiles: [
+ available,
+ {
+ ...available,
+ referenceId: 'gfs:main:0000000000000000000000000000000b@v1',
+ name: 'old.md',
+ gfs: { drive: 'main', resourceId: '0000000000000000000000000000000b', version: 1 },
+ availability: 'stale',
+ code: 'FILE_REFERENCE_STALE',
+ currentVersion: 4,
+ },
+ {
+ referenceId: `att:message-0:file-9@sha256:${'c'.repeat(64)}`,
+ name: 'earlier.txt',
+ class: 'text',
+ byteLength: 8,
+ sourceKind: 'attachment',
+ availability: 'unsupported',
+ code: 'FILE_REFERENCE_UNSUPPORTED',
+ },
+ ],
+ })
+ expect(block).toBe(
+ '<turn-context>\n' +
+ 'date: 2026-05-19T14:30:00.000Z\n' +
+ 'channel: rpc\n' +
+ 'sender: jose\n' +
+ 'referenced_file: id=gfs:main:0000000000000000000000000000000a@v3 name="plan.md" source=gfs drive=main resourceId=0000000000000000000000000000000a version=3 class=markdown bytes=120 availability=available\n' +
+ 'referenced_file: id=gfs:main:0000000000000000000000000000000b@v1 name="old.md" source=gfs drive=main resourceId=0000000000000000000000000000000b version=1 class=markdown bytes=120 availability=stale code=FILE_REFERENCE_STALE current_version=4\n' +
+ `referenced_file: id=att:message-0:file-9@sha256:${'c'.repeat(64)} name="earlier.txt" source=attachment class=text bytes=8 availability=unsupported code=FILE_REFERENCE_UNSUPPORTED\n` +
+ "If the user's request refers to a referenced file, read it with clerum__gfs_read using its drive and resourceId, and pass its version as expectedVersion. A referenced file whose availability is not available cannot be read in this turn; tell the user why instead of guessing.\n" +
+ '</turn-context>\n\n'
+ )
+ expect(REFERENCED_FILES_INSTRUCTION).toBe(
+ "If the user's request refers to a referenced file, read it with clerum__gfs_read using its drive and resourceId, and pass its version as expectedVersion. A referenced file whose availability is not available cannot be read in this turn; tell the user why instead of guessing."
+ )
+ })
+
+ it('lists attached files before referenced files, each with its own instruction', () => {
+ const block = buildTurnContextBlock({
+ date,
+ channel: { type: 'rpc' },
+ attachedFiles: [
+ {
+ attachmentId: 'file-1',
+ name: 'notes.md',
+ class: 'markdown',
+ byteLength: 42,
+ reader: 'text',
+ mismatch: false,
+ declaredMediaType: 'text/markdown',
+ detectedMediaType: 'text/markdown',
+ },
+ ],
+ referencedFiles: [available],
+ })
+ const lines = block.split('\n')
+ const attachedAt = lines.findIndex(line => line.startsWith('attached_file:'))
+ const referencedAt = lines.findIndex(line => line.startsWith('referenced_file:'))
+ expect(attachedAt).toBeGreaterThan(0)
+ expect(lines[attachedAt + 1]).toBe(ATTACHED_FILES_INSTRUCTION)
+ expect(referencedAt).toBe(attachedAt + 2)
+ expect(lines[referencedAt + 1]).toBe(REFERENCED_FILES_INSTRUCTION)
+ })
+
+ it('quotes the user-chosen name so an embedded quote cannot end the field', () => {
+ const block = buildTurnContextBlock({
+ date,
+ channel: { type: 'rpc' },
+ referencedFiles: [{ ...available, name: 'a" availability=available b.md' }],
+ })
+ expect(block).toContain('name="a\\" availability=available b.md" source=gfs drive=main')
+ })
+
+ it('emits neither lines nor instruction for a turn without references', () => {
+ for (const referencedFiles of [undefined, []]) {
+ const block = buildTurnContextBlock({ date, channel: { type: 'rpc' }, referencedFiles })
+ // Witness: the block was built with its channel line.
+ expect(block).toBe(
+ '<turn-context>\ndate: 2026-05-19T14:30:00.000Z\nchannel: rpc\n</turn-context>\n\n'
+ )
+ expect(block).not.toContain('referenced_file')
+ expect(block).not.toContain('clerum__gfs_read')
+ }
+ })
+})
diff --git a/mcp-host/src/core/orchestration/turnContext.ts b/mcp-host/src/core/orchestration/turnContext.ts
index 9ed955f0f..f47ca84fa 100644
--- a/mcp-host/src/core/orchestration/turnContext.ts
+++ b/mcp-host/src/core/orchestration/turnContext.ts
@@ -16,7 +16,9 @@
*
* For cron-originated turns we append two extra lines (`cron_job` /
* `scheduled_for`) — see P1-004. Turns with `kind:'file'` attachments list
- * one `attached_file` line per file plus a fixed read instruction (#666).
+ * one `attached_file` line per file plus a fixed read instruction (#666);
+ * turns with structured file references list one `referenced_file` line per
+ * reference, with its availability, plus their own read instruction.
*/
import type { Attachment } from '../types'
@@ -45,16 +47,52 @@ export interface TurnContextAttachedFile {
detectedMediaType: string
}
+/**
+ * A file referenced by this turn (#666), as admission resolved it under the
+ * Host principal. Only metadata reaches the model: an available GFS file is
+ * read on demand with `clerum__gfs_read`, pinned to `version`.
+ */
+export interface TurnContextReferencedFile {
+ referenceId: string
+ name: string
+ class: string
+ byteLength: number
+ /** Present for GFS references; absent for any other source. */
+ gfs?: { drive: string; resourceId: string; version: number }
+ sourceKind: string
+ availability: string
+ /** The availability code; absent when the file is available. */
+ code?: string
+ /** The version gfsc reported for a stale reference. */
+ currentVersion?: number
+}
+
export interface TurnContextInput {
date: Date
channel: TurnContextChannel
cron?: TurnContextCron
attachedFiles?: TurnContextAttachedFile[]
+ referencedFiles?: TurnContextReferencedFile[]
}
export const ATTACHED_FILES_INSTRUCTION =
"If the user's request refers to an attached file, read it with clerum__attachment_read before answering. Files with reader=none cannot be read in this turn; say so instead of guessing."
+export const REFERENCED_FILES_INSTRUCTION =
+ "If the user's request refers to a referenced file, read it with clerum__gfs_read using its drive and resourceId, and pass its version as expectedVersion. A referenced file whose availability is not available cannot be read in this turn; tell the user why instead of guessing."
+
+function referencedFileLine(file: TurnContextReferencedFile): string {
+ // The name is user-chosen: JSON quoting keeps a `"` inside it from ending the field.
+ let line = `referenced_file: id=${file.referenceId} name=${JSON.stringify(file.name)} source=${file.sourceKind}`
+ if (file.gfs) {
+ line += ` drive=${file.gfs.drive} resourceId=${file.gfs.resourceId} version=${file.gfs.version}`
+ }
+ line += ` class=${file.class} bytes=${file.byteLength} availability=${file.availability}`
+ if (file.code) line += ` code=${file.code}`
+ if (file.currentVersion !== undefined) line += ` current_version=${file.currentVersion}`
+ return line
+}
+
function attachedFileLine(file: TurnContextAttachedFile): string {
// The name is user-chosen: JSON quoting keeps a `"` inside it from ending the field.
const line = `attached_file: id=${file.attachmentId} name=${JSON.stringify(file.name)} class=${file.class} bytes=${file.byteLength} reader=${file.reader}`
@@ -101,5 +139,9 @@ export function buildTurnContextBlock(input: TurnContextInput): string {
lines.push(...input.attachedFiles.map(attachedFileLine))
lines.push(ATTACHED_FILES_INSTRUCTION)
}
+ if (input.referencedFiles && input.referencedFiles.length > 0) {
+ lines.push(...input.referencedFiles.map(referencedFileLine))
+ lines.push(REFERENCED_FILES_INSTRUCTION)
+ }
return `<turn-context>\n${lines.join('\n')}\n</turn-context>\n\n`
}
diff --git a/mcp-host/src/internalTools/gfs.expectedVersion.test.ts b/mcp-host/src/internalTools/gfs.expectedVersion.test.ts
new file mode 100644
index 000000000..23308bd81
--- /dev/null
+++ b/mcp-host/src/internalTools/gfs.expectedVersion.test.ts
@@ -0,0 +1,127 @@
+/**
+ * #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, 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) {
+ 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': FILE_URI, '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).find(t => t.name === 'clerum__gfs_read')!
+ const contentRequests = () =>
+ request.mock.calls.filter(([path]) => path.includes('/content?')).length
+ return { 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)
+ })
+})
diff --git a/mcp-host/src/internalTools/gfs.ts b/mcp-host/src/internalTools/gfs.ts
index 71932f09e..d2624a4d8 100644
--- a/mcp-host/src/internalTools/gfs.ts
+++ b/mcp-host/src/internalTools/gfs.ts
@@ -165,19 +165,34 @@ export function buildGfsReadTools(client: GfscReadClient): InternalToolDefinitio
{
name: 'clerum__gfs_read',
description:
- 'Read a GFS file by drive + resourceId. Returns UTF-8 text, or a bounded JPEG/PNG image when the active model supports image input. Other binary formats return a reference; malformed or unsupported JPEG/PNG returns an error.',
- parameters: driveResourceParams,
+ 'Read a GFS file by drive + resourceId. Returns UTF-8 text, or a bounded JPEG/PNG image when the active model supports image input. Other binary formats return a reference; malformed or unsupported JPEG/PNG returns an error. ' +
+ 'For a referenced_file in the turn context, pass its version as expectedVersion; if the file changed since it was referenced, the result has availability "stale" and no content.',
+ parameters: {
+ ...driveResourceParams,
+ properties: {
+ ...driveResourceParams.properties,
+ expectedVersion: {
+ type: 'integer',
+ minimum: 0,
+ description: 'Read only this version of the file (the version of a referenced_file).',
+ },
+ },
+ },
execute: async (
args: Record<string, unknown>,
_outputDir: string,
options?: InternalToolExecutionOptions
): Promise<InternalToolResult> => {
+ const { expectedVersion, ...target } = args
+ if (expectedVersion !== undefined && !isValidIfMatch(expectedVersion))
+ return invalidArgs('expectedVersion must be a non-negative integer.')
let file: GfsFileContent | undefined
try {
- file = await client.read(args as { drive: string; resourceId: string }, {
+ file = await client.read(target as { drive: string; resourceId: string }, {
...callOptions(options),
timeoutMs: options?.timeoutMs,
budget: options?.readBudget ?? options?.visualInput?.budget,
+ ...(expectedVersion === undefined ? {} : { expectedVersion }),
})
if (options?.signal?.aborted) throw new VisualInputError('cancelled')
const image = inspectImage(file.bytes)
@@ -218,6 +233,19 @@ export function buildGfsReadTools(client: GfscReadClient): InternalToolDefinitio
if (isSvgText(text)) return fileReference(file, 'svg_visual_input_not_supported')
return ok(text)
} catch (err) {
+ // #666 — with an expected version, a version conflict is an answer about
+ // the reference, not a read failure.
+ if (
+ expectedVersion !== undefined &&
+ err instanceof VisualInputError &&
+ err.code === 'version_conflict'
+ )
+ return ok({
+ availability: 'stale',
+ drive: target.drive,
+ resourceId: target.resourceId,
+ expectedVersion,
+ })
return fail(err)
} finally {
file?.reservation.release()
diff --git a/mcp-host/src/internalTools/gfsContentRead.expectedVersion.test.ts b/mcp-host/src/internalTools/gfsContentRead.expectedVersion.test.ts
new file mode 100644
index 000000000..7603a4086
--- /dev/null
+++ b/mcp-host/src/internalTools/gfsContentRead.expectedVersion.test.ts
@@ -0,0 +1,85 @@
+/**
+ * #666 — `expectedVersion` binds a structured file reference to the version it
+ * was taken at: a different metadata snapshot fails before any content request.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { VisualInputBudget } from '../visualInput/policy'
+import { readGfsContent } from './gfsContentRead'
+
+const FILE_ID = '1234567890abcdef1234567890abcdef'
+const FILE_URI = `gfs://main/${FILE_ID}`
+const READ_ARGS = { drive: 'main', resourceId: FILE_ID }
+const SENTINEL = Buffer.from('SENTINEL-666-gfs-version')
+
+function harness(version: number) {
+ 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,
+ bytes: SENTINEL.length,
+ },
+ }),
+ { headers: { 'content-type': 'application/json' } }
+ )
+ return new Response(new Uint8Array(SENTINEL), {
+ headers: {
+ 'x-gfs-uri': FILE_URI,
+ 'x-gfs-version': String(version),
+ 'content-length': String(SENTINEL.length),
+ },
+ })
+ })
+ const contentRequests = () =>
+ request.mock.calls.filter(([path]) => path.includes('/content?')).length
+ const metadataRequests = () =>
+ request.mock.calls.filter(([path]) => !path.includes('/content?')).length
+ return { request, contentRequests, metadataRequests, budget: new VisualInputBudget() }
+}
+
+describe('readGfsContent expectedVersion (#666)', () => {
+ it.each([3, 0])('returns the bytes when the snapshot is at version %i', async version => {
+ const { request, contentRequests, budget } = harness(version)
+ const result = await readGfsContent(request, READ_ARGS, { budget, expectedVersion: version })
+ expect(result.bytes.equals(SENTINEL)).toBe(true)
+ expect(result.source).toMatchObject({ gfsUri: FILE_URI, version })
+ expect(contentRequests()).toBe(1)
+ result.reservation.release()
+ expect(budget.residentBytes).toBe(0)
+ })
+
+ it.each([
+ [3, 4],
+ [3, 0],
+ [0, 1],
+ ])(
+ 'fails with version_conflict before requesting content (snapshot v%i, expected v%i)',
+ async (version, expectedVersion) => {
+ const { request, contentRequests, metadataRequests, budget } = harness(version)
+ await expect(
+ readGfsContent(request, READ_ARGS, { budget, expectedVersion })
+ ).rejects.toMatchObject({ code: 'version_conflict' })
+ // Witness: the metadata snapshot was read, and the decision was made on it.
+ expect(metadataRequests()).toBe(1)
+ expect(contentRequests()).toBe(0)
+ expect(budget.readBytes).toBe(0)
+ expect(budget.residentBytes).toBe(0)
+ }
+ )
+
+ it('reads any version when no expectedVersion is given', async () => {
+ const { request, contentRequests, budget } = harness(7)
+ const result = await readGfsContent(request, READ_ARGS, { budget })
+ expect(result.source.version).toBe(7)
+ expect(contentRequests()).toBe(1)
+ result.reservation.release()
+ })
+})
diff --git a/mcp-host/src/internalTools/gfsContentRead.ts b/mcp-host/src/internalTools/gfsContentRead.ts
index 5970167d4..b8f0a6419 100644
--- a/mcp-host/src/internalTools/gfsContentRead.ts
+++ b/mcp-host/src/internalTools/gfsContentRead.ts
@@ -200,6 +200,11 @@ export async function readGfsContent(
metadataReservation.release()
}
if (signal.aborted) throw new VisualInputError('cancelled')
+ if (
+ options.expectedVersion !== undefined &&
+ snapshot.source.version !== options.expectedVersion
+ )
+ throw new VisualInputError('version_conflict')
if (snapshot.size > budget.remainingReadBytes) throw new VisualInputError('limit_exceeded')
// The source snapshot provides an exact bound: chunks and concatenation can
// coexist, so reserve twice that size before beginning the content request.
diff --git a/mcp-host/src/internalTools/gfsReadTypes.ts b/mcp-host/src/internalTools/gfsReadTypes.ts
index 29effe57b..bb89f6aca 100644
--- a/mcp-host/src/internalTools/gfsReadTypes.ts
+++ b/mcp-host/src/internalTools/gfsReadTypes.ts
@@ -5,6 +5,12 @@ export interface GfsReadOptions {
timeoutMs?: number
deadlineMs?: number
budget?: VisualInputBudget
+ /**
+ * #666 — the version a structured file reference was taken at. A metadata
+ * snapshot at any other version fails with `version_conflict` before the
+ * content is requested.
+ */
+ expectedVersion?: number
}
/** A validated metadata/content snapshot. This object is never a tool result. */
diff --git a/mcp-host/src/lifecycle/taskLifecycle.ts b/mcp-host/src/lifecycle/taskLifecycle.ts
index 0fabaa057..082ad1260 100644
--- a/mcp-host/src/lifecycle/taskLifecycle.ts
+++ b/mcp-host/src/lifecycle/taskLifecycle.ts
@@ -72,6 +72,9 @@ export class TaskLifecycle extends EventEmitter {
// Admission already replaced `attachments` with the validated list.
acceptedAttachmentIds:
task.sourceMessage?.attachments?.map(attachment => attachment.id) ?? [],
+ // Admission set the resolutions; a caller-supplied value never reaches here.
+ acceptedFileReferenceIds:
+ task.sourceMessage?.fileReferenceResolutions?.map(r => r.reference.id) ?? [],
traceContext: task.traceContext ?? null,
createdAt: now,
}
diff --git a/mcp-host/src/lifecycle/types.ts b/mcp-host/src/lifecycle/types.ts
index c410aaaf3..4bd47ed62 100644
--- a/mcp-host/src/lifecycle/types.ts
+++ b/mcp-host/src/lifecycle/types.ts
@@ -77,6 +77,8 @@ export interface TaskRecord {
* delivery answers with them, exactly like the first response did.
*/
acceptedAttachmentIds: readonly string[]
+ /** Ids of the structured file references resolved for this task (#666). */
+ acceptedFileReferenceIds: readonly string[]
traceContext: TraceContextV1 | null
createdAt: Date
dispatchedAt?: Date
diff --git a/mcp-host/src/main.ts b/mcp-host/src/main.ts
index bb47a8ce2..0c4218bc4 100644
--- a/mcp-host/src/main.ts
+++ b/mcp-host/src/main.ts
@@ -61,6 +61,7 @@ import {
resolveGuardrailHookDescriptors,
withResolvedHookDescriptors,
} from './guardrailHookResolver'
+import { createGfscClient, getGfsToolScopes } from './internalTools/gfsClient'
import { HostWatcher, LlmHookWatcher, getHost, getLlmHook } from './k8sClient'
import { StatelessHeartbeat } from './lifecycle/statelessHeartbeat'
import { TaskLifecycle } from './lifecycle/taskLifecycle'
@@ -164,6 +165,7 @@ import {
UsageReporter,
createGovernedRunReporter,
} from './usage/usageReporter'
+import { VISUAL_INPUT_LIMITS } from './visualInput/policy'
import { setOutputDirHostAccessor } from './workflow/internalTools'
import { loadPersistedWorkflowControlToken } from './workflow/mcpHostJwtState'
import { submitProviderWorkflowApprovalDecision } from './workflow/providerWorkflowApprovalDecisionClient'
@@ -1995,10 +1997,22 @@ function handleIncomingMessage(
message,
messageQueue,
() => prepareIncomingMessage(message, options),
- () => dispatchIncomingMessage({ ...message, imageModel: undefined }, options)
+ () =>
+ dispatchIncomingMessage(
+ { ...message, imageModel: undefined, fileReferenceResolutions: undefined },
+ options
+ )
)
}
+// Issue #666 — file references are re-authorized with the Host's own GFS
+// token. The scope is read per message, as the tool registry reads it per
+// registration; the retry budget is the admission deadline, not a tool timeout.
+const fileReferenceGfsEnv = { get: (key: string): string | undefined => process.env[key] }
+const fileReferenceGfscClient = createGfscClient(fileReferenceGfsEnv, {
+ maxRetryWaitMs: VISUAL_INPUT_LIMITS.validationTimeoutMs,
+})
+
const prepareIncomingMessage = createIncomingAdmission({
limits: {
maxCount: INCOMING_ATTACHMENT_MAX_COUNT,
@@ -2014,6 +2028,8 @@ const prepareIncomingMessage = createIncomingAdmission({
resolveImageInput,
applySessionModelSelection,
dispatch: dispatchIncomingMessage,
+ fileReferenceClient: () =>
+ getGfsToolScopes(fileReferenceGfsEnv)?.has('gfs.read') ? fileReferenceGfscClient : null,
logger,
})
diff --git a/mcp-host/src/messageHandler.ts b/mcp-host/src/messageHandler.ts
index 0dfacfa82..f12a0dbb7 100644
--- a/mcp-host/src/messageHandler.ts
+++ b/mcp-host/src/messageHandler.ts
@@ -325,11 +325,17 @@ export class IncomingMessageHandler {
'Duplicate delivery suppressed'
)
const record = this.deps.taskLifecycle.get(priorTaskId)
- // #666 — a success names the attachments the first delivery admitted, as
- // the first response did; without them a client reads a Host that dropped them.
- const accepted = record?.acceptedAttachmentIds.length
- ? { acceptedAttachmentIds: [...record.acceptedAttachmentIds] }
- : {}
+ // #666 — a success names the attachments and file references the first
+ // delivery admitted, as the first response did; without them a client reads
+ // a Host that dropped them.
+ const accepted = {
+ ...(record?.acceptedAttachmentIds.length
+ ? { acceptedAttachmentIds: [...record.acceptedAttachmentIds] }
+ : {}),
+ ...(record?.acceptedFileReferenceIds.length
+ ? { acceptedFileReferenceIds: [...record.acceptedFileReferenceIds] }
+ : {}),
+ }
if (priorStatus === 'completed') {
return {
success: true,
diff --git a/mcp-host/src/server/__tests__/messageRoute.test.ts b/mcp-host/src/server/__tests__/messageRoute.test.ts
index 5398d0f26..0515bcd94 100644
--- a/mcp-host/src/server/__tests__/messageRoute.test.ts
+++ b/mcp-host/src/server/__tests__/messageRoute.test.ts
@@ -1,6 +1,7 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import type { Request, Response } from 'express'
import { createHash } from 'node:crypto'
+import { buildGfsFileReference, classifyBytes } from '@clerum/gfs-interaction-policy'
import { type IncomingAdmissionDeps, createIncomingAdmission } from '../../agent/incomingAdmission'
import { config } from '../../config'
import { ConversationError, ConversationErrorCode } from '../../core/errors'
@@ -334,6 +335,7 @@ describe('handleMessageRoute — acceptedAttachmentIds through the real admissio
resolveImageInput: () => undefined,
applySessionModelSelection: vi.fn(),
dispatch,
+ fileReferenceClient: () => null,
logger: { info: vi.fn(), warn: vi.fn() },
})
return { dispatch, handlers: makeHandlers({ messageHandler }) }
@@ -403,3 +405,131 @@ describe('handleMessageRoute — acceptedAttachmentIds through the real admissio
expect(captured.jsonBody).toEqual(ack)
})
})
+
+describe('handleMessageRoute — structured file references (#666)', () => {
+ function reference(index: number, overrides: Record<string, unknown> = {}) {
+ const rid = index.toString(16).padStart(32, '0')
+ const built = buildGfsFileReference({
+ drive: 'main',
+ resourceId: rid,
+ gfsUri: `gfs://main/${rid}`,
+ version: 1,
+ name: `doc-${index}.md`,
+ declaredMediaType: 'text/markdown',
+ byteLength: 10,
+ classification: classifyBytes({
+ bytes: new Uint8Array(0),
+ totalByteLength: 10,
+ declaredMediaType: 'text/markdown',
+ filename: `doc-${index}.md`,
+ }),
+ })
+ if (!built.ok) throw new Error(built.message)
+ return { ...built.value, ...overrides }
+ }
+
+ function route() {
+ const dispatch = vi.fn<IncomingAdmissionDeps['dispatch']>(() => ({
+ success: true,
+ status: 'pending',
+ taskId: 'task-1',
+ }))
+ const messageHandler = createIncomingAdmission({
+ limits: { maxCount: 20, maxBytes: 1_000_000, maxFileBytes: 1_000_000 },
+ queueReady: () => true,
+ degradedReason: () => null,
+ hostProvider: () => 'zai',
+ getConversationByKey: async () => undefined,
+ resolveTaskModel: () => null,
+ resolveImageInput: () => undefined,
+ applySessionModelSelection: vi.fn(),
+ dispatch,
+ fileReferenceClient: () => null,
+ logger: { info: vi.fn(), warn: vi.fn() },
+ })
+ return { dispatch, handlers: makeHandlers({ messageHandler }) }
+ }
+
+ function request(fileReferences: unknown) {
+ return {
+ runtimeCaller: { caller: 'rpc-proxy', hostRef: 'chatllm', userId: 'legit-user' },
+ body: {
+ sender: 'legit-user',
+ channelType: 'rpc',
+ channelId: 'agent-x',
+ threadId: 'chat-1',
+ content: 'Summarize the referenced file',
+ timestamp: 'now',
+ messageId: 'm-ref',
+ hostRef: 'chatllm',
+ fileReferences,
+ },
+ query: {},
+ } as unknown as Request
+ }
+
+ it('dispatches the parsed references and names them on the ack', async () => {
+ const refs = [reference(1), reference(2)]
+ const { dispatch, handlers } = route()
+ const captured = makeRes()
+ await handleMessageRoute(request(refs), captured.res, handlers)
+ expect(captured.statusCode).toBe(200)
+ expect(dispatch).toHaveBeenCalledTimes(1)
+ expect(dispatch.mock.calls[0]![0].fileReferences).toEqual(refs)
+ expect(captured.jsonBody).toEqual({
+ success: true,
+ status: 'pending',
+ taskId: 'task-1',
+ acceptedFileReferenceIds: refs.map(r => r.id),
+ })
+ })
+
+ it('accepts exactly the configured maximum', async () => {
+ const refs = Array.from({ length: config.fileReferenceMaxCount }, (_, i) => reference(i + 1))
+ const { dispatch, handlers } = route()
+ const captured = makeRes()
+ await handleMessageRoute(request(refs), captured.res, handlers)
+ expect(captured.statusCode).toBe(200)
+ expect(dispatch).toHaveBeenCalledTimes(1)
+ })
+
+ it.each([
+ [
+ 'more references than the limit',
+ () => Array.from({ length: config.fileReferenceMaxCount + 1 }, (_, i) => reference(i + 1)),
+ 'FILE_REFERENCE_INVALID',
+ ],
+ ['a non-list value', () => ({ id: 'x' }), 'FILE_REFERENCE_INVALID'],
+ ['a null value', () => null, 'FILE_REFERENCE_INVALID'],
+ [
+ 'an unsupported schema version',
+ () => [reference(1, { schemaVersion: 2 })],
+ 'FILE_REFERENCE_SCHEMA_VERSION_UNSUPPORTED',
+ ],
+ [
+ 'a gfsUri on another drive',
+ () => {
+ const ref = reference(1)
+ if (ref.source.kind !== 'gfs') throw new Error('expected a GFS reference')
+ return [
+ { ...ref, source: { ...ref.source, gfsUri: `gfs://other/${ref.source.resourceId}` } },
+ ]
+ },
+ 'FILE_REFERENCE_INVALID',
+ ],
+ ])('refuses %s with 400 before dispatch', async (_label, value, code) => {
+ const { dispatch, handlers } = route()
+ // Control: a valid reference on the same route reaches dispatch.
+ await handleMessageRoute(request([reference(1)]), makeRes().res, handlers)
+ expect(dispatch).toHaveBeenCalledTimes(1)
+
+ const captured = makeRes()
+ await handleMessageRoute(request(value()), captured.res, handlers)
+ expect(captured.statusCode).toBe(400)
+ expect(captured.jsonBody).toEqual({
+ success: false,
+ error: { code, message: expect.any(String), retryable: false, provider: 'unknown' },
+ })
+ expect(dispatch).toHaveBeenCalledTimes(1)
+ })
+})
diff --git a/mcp-host/src/server/routes.ts b/mcp-host/src/server/routes.ts
index cc0eacc4a..80d430ba3 100644
--- a/mcp-host/src/server/routes.ts
+++ b/mcp-host/src/server/routes.ts
@@ -1,4 +1,6 @@
import type { Request, Response } from 'express'
+import { parseIncomingFileReferences } from '../agent/fileReferenceResolver'
+import { config } from '../config'
import { ConversationError, ConversationErrorCode } from '../core/errors'
import type { ApprovalDecision } from '../core/extensions/approvalTypes'
import { isTraceContextV1 } from '../core/types'
@@ -314,6 +316,28 @@ export async function handleMessageRoute(
return
}
+ // Issue #666 — a malformed reference or an unknown schema version refuses
+ // the whole message: the turn must not run without the file it names.
+ const fileReferences = parseIncomingFileReferences(
+ message.fileReferences,
+ config.fileReferenceMaxCount
+ )
+ if (!fileReferences.ok) {
+ json(res, 400, {
+ success: false,
+ error: {
+ code: fileReferences.code,
+ message: fileReferences.message,
+ retryable: false,
+ provider: 'unknown',
+ },
+ })
+ return
+ }
+ message.fileReferences = fileReferences.references.length
+ ? fileReferences.references
+ : undefined
+
// Identity invariant for the desktop / rpc channel: the sender MUST be the
// trusted rpc-proxy edge user, regardless of what the body claims.
// rpc-proxy already does this; re-enforcing here is defense-in-depth for
diff --git a/mcp-host/src/server/types.ts b/mcp-host/src/server/types.ts
index a4ca2a072..d13cbe3c4 100644
--- a/mcp-host/src/server/types.ts
+++ b/mcp-host/src/server/types.ts
@@ -3,6 +3,8 @@
* the enabled allowlist entry for the Host's provider; `models` is `[hostDefault]`
* (name only) when the allowlist is unavailable (`degraded`).
*/
+import type { FileReferenceV1 } from '@clerum/gfs-interaction-policy'
+import type { FileReferenceResolution } from '../agent/fileReferenceResolver'
import type { ModelWireEntry } from '../config/modelResolution.js'
import type { ApprovalDecision } from '../core/extensions/approvalTypes'
import type { Attachment, TraceContextV1 } from '../core/types'
@@ -54,6 +56,13 @@ export interface IncomingMessage {
modelSelectionRevision?: number
/** Server-owned immutable visual selection; incoming callers cannot set it. */
imageModel?: { provider: string; model: string }
+ /**
+ * Issue #666 — structured references to files the user picked (Global
+ * Files). The route validates them; admission resolves each against gfsc.
+ */
+ fileReferences?: FileReferenceV1[]
+ /** Server-owned: admission's resolution of `fileReferences`; callers cannot set it. */
+ fileReferenceResolutions?: FileReferenceResolution[]
}
export type RuntimeCallerKind = 'rpc-proxy' | 'channel-reader' | 'workflow-approval-request-reader'
@@ -85,6 +94,12 @@ export interface MessageResponse {
* Host that cannot read file attachments.
*/
acceptedAttachmentIds?: string[]
+ /**
+ * Issue #666 — ids of every structured file reference the Host resolved and
+ * listed in the turn, whatever its availability. Absent when the message
+ * carried none and on every refusal.
+ */
+ acceptedFileReferenceIds?: string[]
/**
* Issue #654 — the session's model-selection revision after the Host accepted
* a piggybacked `model`, or the winning revision on a CAS conflict.
diff --git a/rpc-proxy/package-lock.json b/rpc-proxy/package-lock.json
index 1e5967806..24d635091 100644
--- a/rpc-proxy/package-lock.json
+++ b/rpc-proxy/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-rpc-proxy",
- "version": "0.1.90",
+ "version": "0.1.91",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-rpc-proxy",
- "version": "0.1.90",
+ "version": "0.1.91",
"dependencies": {
"cors": "^2.8.5",
"express": "^4.21.2",
diff --git a/rpc-proxy/package.json b/rpc-proxy/package.json
index cf15847a3..6b775fd3f 100644
--- a/rpc-proxy/package.json
+++ b/rpc-proxy/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-rpc-proxy",
- "version": "0.1.90",
+ "version": "0.1.91",
"description": "External-facing RPC proxy for tenant-scoped MCP access",
"main": "dist/main.js",
"engines": {
diff --git a/rpc-proxy/src/__tests__/sender-assignment.test.ts b/rpc-proxy/src/__tests__/sender-assignment.test.ts
index 8edf0fa25..60f1591f0 100644
--- a/rpc-proxy/src/__tests__/sender-assignment.test.ts
+++ b/rpc-proxy/src/__tests__/sender-assignment.test.ts
@@ -152,6 +152,87 @@ describe('POST /rpc/hosts/:hostRef/messages — sender assignment invariant', ()
})
})
+describe('POST /rpc/hosts/:hostRef/messages — structured file references (#666)', () => {
+ const RID = '1234567890abcdef1234567890abcdef'
+ const fileReference = {
+ schemaVersion: 1,
+ id: `gfs:main:${RID}@v3`,
+ source: {
+ kind: 'gfs',
+ drive: 'main',
+ resourceId: RID,
+ gfsUri: `gfs://main/${RID}`,
+ version: 3,
+ },
+ name: 'plan.md',
+ declaredMediaType: 'text/markdown',
+ detectedMediaType: 'text/markdown',
+ class: 'markdown',
+ detection: 'declared',
+ mismatch: false,
+ byteLength: 120,
+ textReadable: true,
+ reader: 'text',
+ modelImageInput: 'unsupported',
+ }
+
+ beforeEach(() => {
+ authTokenMock.verifyRpcToken.mockReturnValue(VALID_CLAIMS)
+ serviceMock.resolveHostConnectionForUser.mockResolvedValue(HOST_CONNECTION)
+ })
+
+ afterEach(() => {
+ vi.restoreAllMocks()
+ })
+
+ it('forwards the references verbatim and relays the accepted ids', async () => {
+ serviceMock.forwardHostMessageToHost.mockResolvedValue({
+ success: true,
+ status: 'pending',
+ taskId: 'task-1',
+ acceptedFileReferenceIds: [fileReference.id],
+ })
+ const response = await request(makeApp())
+ .post('/rpc/hosts/chatllm/messages')
+ .set('authorization', 'Bearer token')
+ .send({ content: 'Summarize the plan', threadId: 'chat-1', fileReferences: [fileReference] })
+ .expect(200)
+
+ expect(serviceMock.forwardHostMessageToHost).toHaveBeenCalledTimes(1)
+ const forwardedBody = serviceMock.forwardHostMessageToHost.mock.calls[0][1]
+ expect(forwardedBody.fileReferences).toEqual([fileReference])
+ expect(response.body.acceptedFileReferenceIds).toEqual([fileReference.id])
+ })
+
+ it('leaves a malformed value for mcp-host to refuse with its typed code', async () => {
+ serviceMock.forwardHostMessageToHost.mockResolvedValue({ success: true, status: 'completed' })
+ await request(makeApp())
+ .post('/rpc/hosts/chatllm/messages')
+ .set('authorization', 'Bearer token')
+ .send({ content: 'hi', fileReferences: { id: 'not-a-list' } })
+ .expect(200)
+
+ expect(serviceMock.forwardHostMessageToHost.mock.calls[0][1].fileReferences).toEqual({
+ id: 'not-a-list',
+ })
+ })
+
+ it('omits the field when the client sends no references', async () => {
+ serviceMock.forwardHostMessageToHost.mockResolvedValue({ success: true, status: 'completed' })
+ await request(makeApp())
+ .post('/rpc/hosts/chatllm/messages')
+ .set('authorization', 'Bearer token')
+ .send({ content: 'hi', threadId: 'chat-1' })
+ .expect(200)
+
+ // Witness: the message was forwarded with its content.
+ expect(serviceMock.forwardHostMessageToHost).toHaveBeenCalledTimes(1)
+ const forwardedBody = serviceMock.forwardHostMessageToHost.mock.calls[0][1]
+ expect(forwardedBody.content).toBe('hi')
+ expect(forwardedBody).not.toHaveProperty('fileReferences')
+ })
+})
+
describe('POST /rpc/hosts/:hostRef/approvals/approve — userId identity invariant', () => {
beforeEach(() => {
authTokenMock.verifyRpcToken.mockReturnValue({
diff --git a/rpc-proxy/src/routes/rpc.ts b/rpc-proxy/src/routes/rpc.ts
index ddaae9b74..9181da059 100644
--- a/rpc-proxy/src/routes/rpc.ts
+++ b/rpc-proxy/src/routes/rpc.ts
@@ -391,6 +391,7 @@ export function createRpcRouter(): Router {
metadata: rpcInvocationContext(auth),
threadId: desktopSessionId,
attachments: Array.isArray(body.attachments) ? body.attachments : undefined,
+ ...(body.fileReferences === undefined ? {} : { fileReferences: body.fileReferences }),
...(body.modelSelectionRevision === undefined
? {}
: { modelSelectionRevision: body.modelSelectionRevision }),
diff --git a/rpc-proxy/src/services/mcpHostRestService.ts b/rpc-proxy/src/services/mcpHostRestService.ts
index 73c5851c9..fd4efe98f 100644
--- a/rpc-proxy/src/services/mcpHostRestService.ts
+++ b/rpc-proxy/src/services/mcpHostRestService.ts
@@ -122,6 +122,10 @@ export type HostRuntimeMessageRequest = {
// is deduped (replayed) instead of re-executed.
messageId?: string
traceContext?: TraceContextV1
+ // Issue #666 — structured file references (`FileReferenceV1[]`), forwarded
+ // verbatim. mcp-host owns the contract and answers 400 with a typed code
+ // for any malformed value.
+ fileReferences?: unknown
[key: string]: unknown
}