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.tsindex 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 anyservice.desktopGfsUploadStatePath = vidiff --git a/desktop-app/src/__tests__/ipc.fileReferences.test.ts b/desktop-app/src/__tests__/ipc.fileReferences.test.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsxindex 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 }: ComposerGlobalFilesdrive: 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.tsxnew file mode 100644index 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.tsindex 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) returnconst pendingModel = pendingModelForSendconst 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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: stringgfsUri: stringlabel: 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.tsindex 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.jsonindex 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.jsonindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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 | nulllogger: {info: (obj: Record<string, unknown>, msg: string) => voidwarn: (obj: Record<string, unknown>, msg: string) => void@@ -139,7 +147,11 @@ export function createIncomingAdmission(deps: IncomingAdmissionDeps): IncomingAdattachments: 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 } : {}),+ }: responseconst 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 = undefinedif (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): IncomingAdevent: '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.tsindex 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 !== undefinedif (m.contentParts && m.contentParts.length > 0) {diff --git a/mcp-host/src/config.ts b/mcp-host/src/config.tsindex 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: numberactivityBufferSize: numberactivityMaxEventBytes: 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.tsindex 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.tsindex 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.tsindex 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: Datechannel: TurnContextChannelcron?: TurnContextCronattachedFiles?: 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.tsnew file mode 100644index 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.tsindex 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 | undefinedtry {- 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): InternalToolDefinitioif (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.tsnew file mode 100644index 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.tsindex 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.tsindex 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?: numberdeadlineMs?: numberbudget?: 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.tsindex 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.tsindex 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 | nullcreatedAt: DatedispatchedAt?: Datediff --git a/mcp-host/src/main.ts b/mcp-host/src/main.tsindex 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.tsindex 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.tsindex 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 admissioresolveImageInput: () => 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 admissioexpect(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.tsindex 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 fordiff --git a/mcp-host/src/server/types.ts b/mcp-host/src/server/types.tsindex 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.jsonindex 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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?: stringtraceContext?: 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}