Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
fix(mcp-host): answer file reference refusals as 200 and classify check failures
Alfredo Lopezaa2d2d293fcc
diff --git a/external-rest-api/src/releaseManifest.ts b/external-rest-api/src/releaseManifest.tsindex 48d93c83f..f344dba33 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.91',+ rpcProxyVersion: '0.1.92',desktopVersion: '0.9.0',minimumDesktopVersion: '0.1.252',}diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.jsonindex 1694ae127..080e316d2 100644--- a/mcp-host/package-lock.json+++ b/mcp-host/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-mcp-host",- "version": "0.1.446",+ "version": "0.1.447","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-mcp-host",- "version": "0.1.446",+ "version": "0.1.447","license": "SEE LICENSE IN LICENSE","dependencies": {"@anthropic-ai/sdk": "^0.32.0",diff --git a/mcp-host/package.json b/mcp-host/package.jsonindex c76161b2b..2e0aab539 100644--- a/mcp-host/package.json+++ b/mcp-host/package.json@@ -1,6 +1,6 @@{"name": "clerum-mcp-host",- "version": "0.1.446",+ "version": "0.1.447","description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude","main": "dist/main.js","engines": {diff --git a/mcp-host/src/agent/__tests__/fileReferenceGfsGate.test.ts b/mcp-host/src/agent/__tests__/fileReferenceGfsGate.test.tsnew file mode 100644index 000000000..61e342467--- /dev/null+++ b/mcp-host/src/agent/__tests__/fileReferenceGfsGate.test.ts@@ -0,0 +1,68 @@+/**+ * #666 — the per-message gate between the Host's GFS token and file+ * reference resolution.+ */+import { describe, expect, it, vi } from 'vitest'+import type { GfsToolScopeInspection } from '../../internalTools/gfsClient'+import { createFileReferenceGfsGate } from '../fileReferenceGfsGate'+import type { FileReferenceGfscClient } from '../fileReferenceResolver'++function gate(inspection: GfsToolScopeInspection) {+ const client: FileReferenceGfscClient = { resolve: vi.fn() }+ const logger = { warn: vi.fn(), error: vi.fn() }+ const inspectScopes = vi.fn(() => inspection)+ const access = createFileReferenceGfsGate({ inspectScopes, client, logger })+ return { access, client, logger, inspectScopes }+}++describe('createFileReferenceGfsGate (#666)', () => {+ it('returns the client for a token with gfs.read, and logs nothing', () => {+ const { access, client, logger, inspectScopes } = gate({+ status: 'ok',+ scopes: new Set(['gfs.read']),+ })+ expect(access()).toEqual({ status: 'available', client })+ // Witness: the token was inspected for this message.+ expect(inspectScopes).toHaveBeenCalledTimes(1)+ expect(logger.warn).not.toHaveBeenCalled()+ expect(logger.error).not.toHaveBeenCalled()+ })++ it.each([+ ['no token', { status: 'not_configured' } as const, 'not_configured'],+ [+ 'a scope outside the allowlist',+ { status: 'scope_outside_allowlist' } as const,+ 'scope_outside_allowlist',+ ],+ [+ 'gfs.write only',+ { status: 'ok', scopes: new Set(['gfs.write'] as const) } as const,+ 'missing_gfs_read',+ ],+ ['no scopes', { status: 'ok', scopes: new Set<never>() } as const, 'missing_gfs_read'],+ ])('answers unsupported for %s and warns with reason %s', (_label, inspection, reason) => {+ const { access, logger } = gate(inspection)+ expect(access()).toEqual({ status: 'unsupported' })+ expect(logger.warn).toHaveBeenCalledTimes(1)+ expect(logger.warn).toHaveBeenCalledWith(+ { event: 'file_reference_gfs_unavailable', reason },+ 'Host runtime event'+ )+ expect(logger.error).not.toHaveBeenCalled()+ })++ it.each([+ ['token_unreadable', 'TokenReadError'],+ ['token_undecodable', 'TokenDecodeError'],+ ] as const)('refuses on %s with %s and logs an error', (status, errorClass) => {+ const { access, logger } = gate({ status })+ expect(access()).toEqual({ status: 'credentials_failed', errorClass })+ expect(logger.error).toHaveBeenCalledTimes(1)+ expect(logger.error).toHaveBeenCalledWith(+ { event: 'file_reference_gfs_unavailable', reason: status },+ 'Host runtime event'+ )+ expect(logger.warn).not.toHaveBeenCalled()+ })+})diff --git a/mcp-host/src/agent/__tests__/fileReferenceResolver.test.ts b/mcp-host/src/agent/__tests__/fileReferenceResolver.test.tsindex 4c3ca0b25..eb40ac0bf 100644--- a/mcp-host/src/agent/__tests__/fileReferenceResolver.test.ts+++ b/mcp-host/src/agent/__tests__/fileReferenceResolver.test.ts@@ -1,14 +1,17 @@/*** #666 — route-level parsing and gfsc resolution of structured file references.*/-import { describe, expect, it, vi } from 'vitest'+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'+import { mkdtemp, rm, writeFile } from 'node:fs/promises'+import { tmpdir } from 'node:os'+import { join } from 'node:path'import {type FileReferenceV1,buildAttachmentFileReference,buildGfsFileReference,classifyBytes,} from '@clerum/gfs-interaction-policy'-import { GfscHttpError } from '../../internalTools/gfsClient'+import { type GfsRuntimeEnv, GfscHttpError, createGfscClient } from '../../internalTools/gfsClient'import { VISUAL_INPUT_LIMITS } from '../../visualInput/policy'import {FILE_REFERENCE_AVAILABILITY_CODES,@@ -141,6 +144,31 @@ describe('parseIncomingFileReferences (#666)', () => {})})+ it('rejects two versions of the same GFS file, dashed or not', () => {+ const dashed = '12345678-90ab-cdef-1234-567890abcdef'+ const v3 = gfsReference({ resourceId: RID })+ // Witness: each reference is admitted on its own, and so are two files.+ expect(parseIncomingFileReferences([v3], 10)).toMatchObject({ ok: true })+ expect(+ parseIncomingFileReferences([v3, gfsReference({ resourceId: RID_2 })], 10)+ ).toMatchObject({ ok: true, references: [v3, expect.anything()] })+ for (const second of [+ gfsReference({ resourceId: RID, version: 4 }),+ gfsReference({ resourceId: dashed, version: 3 }),+ ]) {+ expect(second.id).not.toBe(v3.id)+ expect(parseIncomingFileReferences([v3, second], 10)).toEqual({+ ok: false,+ code: 'FILE_REFERENCE_INVALID',+ message: 'Each file reference must appear once.',+ })+ }+ // The same resource on another drive is another file.+ expect(+ parseIncomingFileReferences([v3, gfsReference({ resourceId: RID, drive: 'team' })], 10)+ ).toMatchObject({ ok: true })+ })+it.each([['another drive', `gfs://other/${RID}`],['another resource', `gfs://main/${RID_2}`],@@ -238,17 +266,64 @@ describe('resolveFileReferences (#666)', () => {expect(gfsc.resolve).toHaveBeenCalledTimes(1)})- it.each([429, 500, 502, 503, 401])('fails transient on gfsc %i', async status => {+ it.each([429, 500, 502, 503, 599])('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',+ errorClass: 'GfscHttpError',+ status,+ })+ expect(gfsc.resolve).toHaveBeenCalledTimes(1)+ })++ it('fails credentials, not transient, on a gfsc 401', async () => {+ const gfsc = client(() => {+ throw new GfscHttpError(401, 'unauthorized')+ })+ expect(await resolveFileReferences([gfsReference()], gfsc)).toEqual({+ ok: false,+ failure: 'credentials',+ errorClass: 'GfscHttpError',+ status: 401,+ })+ expect(gfsc.resolve).toHaveBeenCalledTimes(1)+ })++ it.each([405, 409, 413, 422])('fails contract on an unexpected gfsc %i', async status => {+ const gfsc = client(() => {+ throw new GfscHttpError(status, 'unexpected')})+ expect(await resolveFileReferences([gfsReference()], gfsc)).toEqual({+ ok: false,+ failure: 'contract',+ errorClass: 'GfscHttpError',+ status,+ })+ })++ it('rethrows a gfsc status outside 4xx and 5xx instead of classifying it', async () => {+ const error = new GfscHttpError(302, 'moved')+ const gfsc = client(() => {+ throw error+ })+ await expect(resolveFileReferences([gfsReference()], gfsc)).rejects.toBe(error)expect(gfsc.resolve).toHaveBeenCalledTimes(1)})+ it('fails transient on a timeout signal', async () => {+ const gfsc = client(() => {+ throw new DOMException('The operation timed out.', 'TimeoutError')+ })+ expect(await resolveFileReferences([gfsReference()], gfsc)).toEqual({+ ok: false,+ failure: 'transient',+ errorClass: 'TimeoutError',+ })+ })+it('fails transient on a network error', async () => {const gfsc = client(() => {throw new TypeError('fetch failed')@@ -256,9 +331,30 @@ describe('resolveFileReferences (#666)', () => {expect(await resolveFileReferences([gfsReference()], gfsc)).toEqual({ok: false,failure: 'transient',+ errorClass: 'TypeError',})})+ it('fails contract on a JSON body that does not parse', async () => {+ const gfsc = client(() => {+ throw new SyntaxError('Unexpected token < in JSON at position 0')+ })+ expect(await resolveFileReferences([gfsReference()], gfsc)).toEqual({+ ok: false,+ failure: 'contract',+ errorClass: 'SyntaxError',+ })+ })++ it('rethrows an error outside the classification table', async () => {+ const error = new RangeError('defect')+ const gfsc = client(() => {+ throw error+ })+ await expect(resolveFileReferences([gfsReference()], gfsc)).rejects.toBe(error)+ expect(gfsc.resolve).toHaveBeenCalledTimes(1)+ })+it('fails invalid on a gfsc 400', async () => {const gfsc = client(() => {throw new GfscHttpError(400, 'path_invalid')@@ -266,6 +362,8 @@ describe('resolveFileReferences (#666)', () => {expect(await resolveFileReferences([gfsReference()], gfsc)).toEqual({ok: false,failure: 'invalid',+ errorClass: 'GfscHttpError',+ status: 400,})})@@ -274,6 +372,7 @@ describe('resolveFileReferences (#666)', () => {expect(await resolveFileReferences([gfsReference()], gfsc)).toEqual({ok: false,failure: 'invalid',+ errorClass: 'SizeMismatch',})expect(gfsc.resolve).toHaveBeenCalledTimes(1)})@@ -292,6 +391,7 @@ describe('resolveFileReferences (#666)', () => {expect(await resolveFileReferences([gfsReference()], gfsc)).toEqual({ok: false,failure: 'contract',+ errorClass: 'UnexpectedMetadata',})expect(gfsc.resolve).toHaveBeenCalledTimes(1)})@@ -305,7 +405,7 @@ describe('resolveFileReferences (#666)', () => {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')))+ call.signal.addEventListener('abort', () => reject(call.signal.reason)))}),}@@ -313,7 +413,12 @@ describe('resolveFileReferences (#666)', () => {[gfsReference(), gfsReference({ resourceId: RID_2 })],gfsc)- expect(result).toEqual({ ok: false, failure: 'transient' })+ expect(result).toEqual({+ ok: false,+ failure: 'transient',+ errorClass: 'GfscHttpError',+ status: 503,+ })// Witness: both calls started before either finished (one shared signal).expect(started).toBe(2)expect(signals[0]).toBe(signals[1])@@ -327,8 +432,9 @@ describe('resolveFileReferences (#666)', () => {const gfsc: FileReferenceGfscClient = {resolve: vi.fn((_args, call) => {deadlineMs = call.deadlineMs+ // fetch rejects with the signal's reason, an AbortError.return new Promise((_resolve, reject) =>- call.signal.addEventListener('abort', () => reject(new Error('aborted')))+ call.signal.addEventListener('abort', () => reject(call.signal.reason)))}),}@@ -343,12 +449,73 @@ describe('resolveFileReferences (#666)', () => {await Promise.resolve()expect(settled).toBe(false)await vi.advanceTimersByTimeAsync(1)- expect(await pending).toEqual({ ok: false, failure: 'transient' })+ expect(await pending).toEqual({ ok: false, failure: 'transient', errorClass: 'AbortError' })} finally {vi.useRealTimers()}})+ describe('through the real gfsc client', () => {+ // The errors below are the ones createGfscClient raises, not stand-ins,+ // so a change to its token handling fails here.+ let dir: string+ beforeAll(async () => {+ dir = await mkdtemp(join(tmpdir(), 'file-reference-token-'))+ })+ afterAll(async () => {+ await rm(dir, { recursive: true, force: true })+ })++ function realClient(tokenFile: string, fetch: GfsRuntimeEnv['fetch']) {+ return createGfscClient(+ { get: key => (key === 'MCP_HOST_GFS_TOKEN_FILE' ? tokenFile : undefined), fetch },+ { maxRetryWaitMs: 0 }+ )+ }++ it('fails credentials when the token file is missing or empty', async () => {+ const empty = join(dir, 'empty-token')+ await writeFile(empty, '\n')+ for (const tokenFile of [join(dir, 'absent-token'), empty]) {+ const fetch = vi.fn<NonNullable<GfsRuntimeEnv['fetch']>>()+ expect(await resolveFileReferences([gfsReference()], realClient(tokenFile, fetch))).toEqual(+ { ok: false, failure: 'credentials', errorClass: 'TokenReadError' }+ )+ expect(fetch).not.toHaveBeenCalled()+ }+ // Witness: with a readable token the same client reaches gfsc.+ const readable = join(dir, 'token')+ await writeFile(readable, 'header.payload.signature\n')+ const fetch = vi.fn<NonNullable<GfsRuntimeEnv['fetch']>>(+ async () =>+ new Response(JSON.stringify(view()), {+ status: 200,+ headers: { 'content-type': 'application/json' },+ })+ )+ expect(await resolveFileReferences([gfsReference()], realClient(readable, fetch))).toEqual({+ ok: true,+ resolutions: [{ availability: 'available', reference: gfsReference() }],+ })+ expect(fetch).toHaveBeenCalledTimes(1)+ })++ it('fails contract when gfsc declares JSON and sends something else', async () => {+ const readable = join(dir, 'token-json')+ await writeFile(readable, 'header.payload.signature\n')+ const fetch = vi.fn<NonNullable<GfsRuntimeEnv['fetch']>>(+ async () =>+ new Response('<html>', { status: 200, headers: { 'content-type': 'application/json' } })+ )+ expect(await resolveFileReferences([gfsReference()], realClient(readable, fetch))).toEqual({+ ok: false,+ failure: 'contract',+ errorClass: 'SyntaxError',+ })+ expect(fetch).toHaveBeenCalledTimes(1)+ })+ })+it('names a code for every unavailable availability', () => {expect(FILE_REFERENCE_AVAILABILITY_CODES).toEqual({not_found: 'FILE_REFERENCE_NOT_FOUND',diff --git a/mcp-host/src/agent/__tests__/incomingAdmission.fileReferences.test.ts b/mcp-host/src/agent/__tests__/incomingAdmission.fileReferences.test.tsindex 13c2e77b5..43d08f616 100644--- a/mcp-host/src/agent/__tests__/incomingAdmission.fileReferences.test.ts+++ b/mcp-host/src/agent/__tests__/incomingAdmission.fileReferences.test.ts@@ -6,13 +6,18 @@import { type Mock, describe, expect, it, vi } from 'vitest'import {type FileReferenceV1,+ buildAttachmentFileReference,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'+import {+ type IncomingAdmissionDeps,+ createIncomingAdmission,+ replayedIncomingMessage,+} from '../incomingAdmission'const RID = '1234567890abcdef1234567890abcdef'const RID_2 = 'abcdefabcdefabcdefabcdefabcdefab'@@ -38,6 +43,26 @@ function gfsReference(resourceId = RID, version = 3): FileReferenceV1 {return built.value}+function attachmentReference(): FileReferenceV1 {+ const bytes = new TextEncoder().encode('hello')+ const built = buildAttachmentFileReference({+ attachmentId: 'a1',+ messageId: 'msg-1',+ 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(resourceId: string, fields: Record<string, unknown> = {}) {return {ok: true,@@ -90,6 +115,11 @@ function makeAdmission(return { ok: true, provider: 'zai', model: 'glm-5.3-flash', modelSelectionRevision: 2 }})+ const fileReferenceGfs = vi.fn<IncomingAdmissionDeps['fileReferenceGfs']>(() =>+ resolveSpy+ ? { status: 'available', client: { resolve: resolveSpy } }+ : { status: 'unsupported' }+ )const info: Mock<IncomingAdmissionDeps['logger']['info']> = vi.fn()const warn: Mock<IncomingAdmissionDeps['logger']['warn']> = vi.fn()const deps: IncomingAdmissionDeps = {@@ -102,7 +132,7 @@ function makeAdmission(resolveImageInput: () => undefined,applySessionModelSelection,dispatch,- fileReferenceClient: () => (resolveSpy ? { resolve: resolveSpy } : null),+ fileReferenceGfs,logger: { info, warn },...overrides,}@@ -110,6 +140,7 @@ function makeAdmission(admit: createIncomingAdmission(deps),dispatch: deps.dispatch as typeof dispatch,resolve: resolveSpy,+ fileReferenceGfs,applySessionModelSelection,info,warn,@@ -160,8 +191,9 @@ describe('incoming admission with file references (#666)', () => {it('marks every reference unsupported, without gfsc, when the Host has no read scope', async () => {const ref = gfsReference()- const { admit, dispatch } = makeAdmission(null)+ const { admit, dispatch, fileReferenceGfs } = makeAdmission(null)const response = (await admit(message({ fileReferences: [ref] }))) as MessageResponse+ expect(fileReferenceGfs).toHaveBeenCalledTimes(1)expect(dispatched(dispatch).fileReferenceResolutions).toEqual([{ availability: 'unsupported', reference: ref },])@@ -188,22 +220,28 @@ describe('incoming admission with file references (#666)', () => {['a transient gfsc failure',() => Promise.reject(new GfscHttpError(503, 'not_mounted')),- { code: 'LLM_API_CALL_FAILED', retryable: true },- 'transient',+ { code: 'FILE_REFERENCE_CHECK_FAILED', retryable: true },+ { failure: 'transient', errorClass: 'GfscHttpError', status: 503 },],['a gfsc 400',() => Promise.reject(new GfscHttpError(400, 'path_invalid')),{ code: 'FILE_REFERENCE_INVALID', retryable: false },- 'invalid',+ { failure: 'invalid', errorClass: 'GfscHttpError', status: 400 },+ ],+ [+ 'a gfsc 401',+ () => Promise.reject(new GfscHttpError(401, 'unauthorized')),+ { code: 'FILE_REFERENCE_CHECK_FAILED', retryable: false },+ { failure: 'credentials', errorClass: 'GfscHttpError', status: 401 },],['metadata about another file',() => Promise.resolve(view(RID_2)),- { code: 'LLM_API_CALL_FAILED', retryable: false },- 'contract',+ { code: 'FILE_REFERENCE_CHECK_FAILED', retryable: false },+ { failure: 'contract', errorClass: 'UnexpectedMetadata', status: null },],- ])('refuses the message on %s', async (_label, answer, error, failure) => {+ ])('refuses the message on %s', async (_label, answer, error, logged) => {const { admit, dispatch, resolve, warn } = makeAdmission(answer)const response = await admit(message({ fileReferences: [gfsReference()] }))expect(response).toEqual({@@ -213,11 +251,64 @@ describe('incoming admission with file references (#666)', () => {// 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.objectContaining({ referenceCount: 1, ...logged }),])expect(dispatch).not.toHaveBeenCalled()})+ it.each([['TokenReadError'], ['TokenDecodeError']] as const)(+ 'refuses without calling gfsc when the Host token fails with %s',+ async errorClass => {+ const { admit, dispatch, resolve, warn, fileReferenceGfs } = makeAdmission(async () =>+ view(RID)+ )+ fileReferenceGfs.mockReturnValue({ status: 'credentials_failed', errorClass })+ const response = await admit(message({ fileReferences: [gfsReference()] }))+ expect(response).toEqual({+ success: false,+ error: {+ code: 'FILE_REFERENCE_CHECK_FAILED',+ message: expect.any(String),+ retryable: false,+ provider: 'zai',+ },+ })+ // Witness: the gate was consulted and its failure was logged.+ expect(fileReferenceGfs).toHaveBeenCalledTimes(1)+ expect(events(warn, 'file_reference_refused')).toEqual([+ expect.objectContaining({ failure: 'credentials', errorClass, status: null }),+ ])+ expect(resolve).not.toHaveBeenCalled()+ expect(dispatch).not.toHaveBeenCalled()+ }+ )++ it('does not consult the GFS gate when every reference names an attachment', async () => {+ const ref = attachmentReference()+ const { admit, dispatch, fileReferenceGfs } = makeAdmission(async () => view(RID))+ fileReferenceGfs.mockReturnValue({ status: 'credentials_failed', errorClass: 'TokenReadError' })+ const response = (await admit(message({ fileReferences: [ref] }))) as MessageResponse+ // Witness: the reference was resolved by the Host and the turn dispatched.+ expect(dispatched(dispatch).fileReferenceResolutions).toEqual([+ { availability: 'unsupported', reference: ref },+ ])+ expect(response.acceptedFileReferenceIds).toEqual([ref.id])+ expect(fileReferenceGfs).not.toHaveBeenCalled()+ })++ it('emits file_reference_resolved only for a message with references', async () => {+ const { admit, dispatch, info } = makeAdmission(async () => view(RID))+ await admit(message({ fileReferences: [gfsReference()] }))+ // Witness: the reference path emitted the event once.+ expect(events(info, 'file_reference_resolved')).toHaveLength(1)++ info.mockClear()+ await admit(message())+ // The text-only message was dispatched, and no resolution was logged for it.+ expect(dispatch).toHaveBeenCalledTimes(2)+ expect(events(info, 'file_reference_resolved')).toHaveLength(0)+ })+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(@@ -283,3 +374,25 @@ describe('incoming admission with file references (#666)', () => {expect(dispatch).not.toHaveBeenCalled()})})++describe('replayedIncomingMessage (#666)', () => {+ it('clears the fields only admission may set and keeps the rest', () => {+ const ref = gfsReference()+ const original = message({+ fileReferences: [ref],+ fileReferenceResolutions: [{ availability: 'available', reference: ref }],+ imageModel: { provider: 'zai', model: 'glm-5v' },+ })+ const replayed = replayedIncomingMessage(original)+ expect(replayed).toEqual({+ ...original,+ imageModel: undefined,+ fileReferenceResolutions: undefined,+ })+ // Witness: the references the caller sent survive the replay.+ expect(replayed.fileReferences).toEqual([ref])+ expect(replayed.fileReferenceResolutions).toBeUndefined()+ expect(replayed.imageModel).toBeUndefined()+ expect(original.fileReferenceResolutions).toHaveLength(1)+ })+})diff --git a/mcp-host/src/agent/__tests__/incomingAdmission.modelSelection.test.ts b/mcp-host/src/agent/__tests__/incomingAdmission.modelSelection.test.tsindex 83230e48c..38d770df9 100644--- a/mcp-host/src/agent/__tests__/incomingAdmission.modelSelection.test.ts+++ b/mcp-host/src/agent/__tests__/incomingAdmission.modelSelection.test.ts@@ -129,7 +129,7 @@ describe('image sends and the session model selection', () => {resolveImageInput,applySessionModelSelection: applySelection,dispatch,- fileReferenceClient: () => null,+ fileReferenceGfs: () => ({ status: 'unsupported' }),logger: { info: vi.fn(), warn: vi.fn() },})})diff --git a/mcp-host/src/agent/fileReferenceGfsGate.ts b/mcp-host/src/agent/fileReferenceGfsGate.tsnew file mode 100644index 000000000..f1030e14d--- /dev/null+++ b/mcp-host/src/agent/fileReferenceGfsGate.ts@@ -0,0 +1,55 @@+/**+ * Issue #666 — whether this Host can re-authorize a message's GFS file+ * references, decided per message from its own GFS token.+ *+ * A Host that has no token, or whose token carries no `gfs.read`, cannot serve+ * GFS references: they are admitted as `unsupported`. A token that is present+ * but cannot be read or decoded is a broken deployment, not a Host without+ * GFS, so the message is refused instead of being answered as if no file were+ * readable.+ */+import type { GfsToolScopeInspection } from '../internalTools/gfsClient'+import type { FileReferenceGfscClient } from './fileReferenceResolver'++export type FileReferenceGfsAccess =+ | { status: 'available'; client: FileReferenceGfscClient }+ | { status: 'unsupported' }+ | { status: 'credentials_failed'; errorClass: 'TokenReadError' | 'TokenDecodeError' }++export interface FileReferenceGfsGateDeps {+ inspectScopes: () => GfsToolScopeInspection+ client: FileReferenceGfscClient+ logger: {+ warn: (obj: Record<string, unknown>, msg: string) => void+ error: (obj: Record<string, unknown>, msg: string) => void+ }+}++export function createFileReferenceGfsGate(+ deps: FileReferenceGfsGateDeps+): () => FileReferenceGfsAccess {+ return () => {+ const inspection = deps.inspectScopes()+ if (inspection.status === 'ok' && inspection.scopes.has('gfs.read'))+ return { status: 'available', client: deps.client }+ if (inspection.status === 'token_unreadable' || inspection.status === 'token_undecodable') {+ deps.logger.error(+ { event: 'file_reference_gfs_unavailable', reason: inspection.status },+ 'Host runtime event'+ )+ return {+ status: 'credentials_failed',+ errorClass:+ inspection.status === 'token_unreadable' ? 'TokenReadError' : 'TokenDecodeError',+ }+ }+ deps.logger.warn(+ {+ event: 'file_reference_gfs_unavailable',+ reason: inspection.status === 'ok' ? 'missing_gfs_read' : inspection.status,+ },+ 'Host runtime event'+ )+ return { status: 'unsupported' }+ }+}diff --git a/mcp-host/src/agent/fileReferenceResolver.ts b/mcp-host/src/agent/fileReferenceResolver.tsindex 8be39aff7..64de9aa70 100644--- a/mcp-host/src/agent/fileReferenceResolver.ts+++ b/mcp-host/src/agent/fileReferenceResolver.ts@@ -5,8 +5,8 @@* 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`.+ * reference. The model reads an available file later with `clerum__gfs_read`,+ * which the Host pins to the reference's version.*/import { type FileReferenceV1, parseFileReferenceV1 } from '@clerum/gfs-interaction-policy'import { FileReferenceErrorCode } from '../core/errors'@@ -95,6 +95,7 @@ export function parseIncomingFileReferences(if (value.length > maxCount) return invalid(`A message can reference at most ${maxCount} files.`)const references: FileReferenceV1[] = []const ids = new Set<string>()+ const gfsFiles = new Set<string>()for (const entry of value) {const parsed = parseFileReferenceV1(entry)if (!parsed.ok) {@@ -108,13 +109,18 @@ export function parseIncomingFileReferences(}}const reference = parsed.value- if (ids.has(reference.id)) return invalid('Each file reference must appear once.')- ids.add(reference.id)+ // A GFS file is keyed by drive and resource, whatever the version: two+ // references to the same file would leave its read pin ambiguous.+ let key = reference.idif (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.')+ key = `${reference.source.drive}/${rid}`}+ const seen = reference.source.kind === 'gfs' ? gfsFiles : ids+ if (seen.has(key)) return invalid('Each file reference must appear once.')+ seen.add(key)references.push(reference)}return { ok: true, references }@@ -128,22 +134,83 @@ export interface FileReferenceGfscClient {): Promise<unknown>}+/**+ * Why a check could not produce resolutions.+ * - `transient`: gfsc was unavailable, slow or rate-limited; the client may resend.+ * - `invalid`: gfsc refused the reference as malformed, or it misstates the file's size.+ * - `contract`: gfsc answered with a status or a body the Host does not understand.+ * - `credentials`: the Host's own GFS token is unreadable, undecodable or refused.+ */+export type FileReferenceCheckFailure = 'transient' | 'invalid' | 'contract' | 'credentials'++/** What failed, from a closed set of names; never an error message. */+export type FileReferenceCheckErrorClass =+ | 'GfscHttpError'+ | 'AbortError'+ | 'TimeoutError'+ | 'TypeError'+ | 'SyntaxError'+ | 'TokenReadError'+ | 'TokenDecodeError'+ | 'UnexpectedMetadata'+ | 'SizeMismatch'+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' }+ | {+ ok: false+ failure: FileReferenceCheckFailure+ errorClass: FileReferenceCheckErrorClass+ /** The gfsc HTTP status, when gfsc answered. */+ status?: number+ }class ResolutionFailure extends Error {- constructor(readonly failure: 'transient' | 'invalid' | 'contract') {+ constructor(+ readonly failure: FileReferenceCheckFailure,+ readonly errorClass: FileReferenceCheckErrorClass,+ readonly status?: number+ ) {super(`file reference resolution failed: ${failure}`)this.name = 'ResolutionFailure'}}+// The error the gfsc client raises for an empty mounted token file.+const EMPTY_TOKEN_FILE_MESSAGE = 'MCP_HOST_GFS_TOKEN_FILE is empty'++function isTokenReadError(error: Error): boolean {+ if (error.message === EMPTY_TOKEN_FILE_MESSAGE) return true+ // A failed read of the mounted token file is a Node system error.+ const { code, syscall } = error as NodeJS.ErrnoException+ return typeof code === 'string' && typeof syscall === 'string'+}++/**+ * Maps a failed gfsc `resolve` call that is not an availability. An error+ * outside this table is rethrown: it is a defect, not a check result.+ */+function checkFailure(error: unknown): ResolutionFailure {+ if (error instanceof GfscHttpError) {+ const { status } = error+ if (status === 401) return new ResolutionFailure('credentials', 'GfscHttpError', status)+ if (status === 429 || (status >= 500 && status <= 599))+ return new ResolutionFailure('transient', 'GfscHttpError', status)+ if (status >= 400 && status <= 499)+ return new ResolutionFailure('contract', 'GfscHttpError', status)+ throw error+ }+ if (error instanceof Error) {+ if (error.name === 'AbortError' || error.name === 'TimeoutError')+ return new ResolutionFailure('transient', error.name)+ if (error instanceof SyntaxError) return new ResolutionFailure('contract', 'SyntaxError')+ if (isTokenReadError(error)) return new ResolutionFailure('credentials', 'TokenReadError')+ // fetch reports a refused, reset or unresolvable connection as a TypeError.+ if (error instanceof TypeError) return new ResolutionFailure('transient', 'TypeError')+ }+ throw error+}+interface ResolvedView {kind: 'file' | 'directory'version: number@@ -162,7 +229,7 @@ function resolvedView(!envelope.data ||typeof envelope.data !== 'object')- throw new ResolutionFailure('contract')+ throw new ResolutionFailure('contract', 'UnexpectedMetadata')const data = envelope.data as Record<string, unknown>const rid = normalizeRid(source.resourceId)if (@@ -177,7 +244,7 @@ function resolvedView(!Number.isSafeInteger(data.bytes) ||(data.bytes as number) < 0)- throw new ResolutionFailure('contract')+ throw new ResolutionFailure('contract', 'UnexpectedMetadata')return { kind: data.kind, version: data.version as number, bytes: data.bytes as number }}@@ -198,9 +265,9 @@ async function resolveOne(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')+ if (error.status === 400) throw new ResolutionFailure('invalid', 'GfscHttpError', 400)}- throw new ResolutionFailure('transient')+ throw checkFailure(error)}const view = resolvedView(body, source)if (view.kind === 'directory') return { availability: 'not_a_file', reference }@@ -208,7 +275,7 @@ async function resolveOne(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 !== reference.byteLength) throw new ResolutionFailure('invalid', 'SizeMismatch')if (view.bytes > VISUAL_INPUT_LIMITS.fileBytes) return { availability: 'too_large', reference }return { availability: 'available', reference }}@@ -231,7 +298,13 @@ export async function resolveFileReferences()return { ok: true, resolutions }} catch (error) {- if (error instanceof ResolutionFailure) return { ok: false, failure: error.failure }+ if (error instanceof ResolutionFailure)+ return {+ ok: false,+ failure: error.failure,+ errorClass: error.errorClass,+ ...(error.status === undefined ? {} : { status: error.status }),+ }throw error} finally {clearTimeout(timer)diff --git a/mcp-host/src/agent/incomingAdmission.ts b/mcp-host/src/agent/incomingAdmission.tsindex 705769815..f5c989ca5 100644--- a/mcp-host/src/agent/incomingAdmission.ts+++ b/mcp-host/src/agent/incomingAdmission.ts@@ -18,7 +18,12 @@ import {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 { FileReferenceGfsAccess } from './fileReferenceGfsGate'+import {+ type FileReferenceCheckFailure,+ type FileReferenceResolutionResult,+ resolveFileReferences,+} from './fileReferenceResolver'import { type IncomingAttachmentLimits, validateIncomingAttachments } from './incomingAttachments'import type { SessionModelSelectionOptions } from './sessionModelSelection'@@ -65,17 +70,26 @@ export interface IncomingAdmissionDeps {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).+ * Issue #666 — the gfsc client that re-authorizes file references. Without a+ * `gfs.read` scope every GFS reference is `unsupported` and gfsc is never+ * called; a token that cannot be read or decoded refuses the message.*/- fileReferenceClient: () => FileReferenceGfscClient | null+ fileReferenceGfs: () => FileReferenceGfsAccesslogger: {info: (obj: Record<string, unknown>, msg: string) => voidwarn: (obj: Record<string, unknown>, msg: string) => void}}+/**+ * The message a replayed delivery is dispatched with. Admission does not run+ * on a replay, so the fields only admission may set are cleared: a caller can+ * never supply a visual execution identity or file reference resolutions.+ */+export function replayedIncomingMessage(message: IncomingMessage): IncomingMessage {+ return { ...message, imageModel: undefined, fileReferenceResolutions: undefined }+}+export type IncomingAdmission = (message: IncomingMessage,options?: { async?: boolean }@@ -159,21 +173,6 @@ export function createIncomingAdmission(deps: IncomingAdmissionDeps): IncomingAd},'Received message')- if (validated.fileReferences.length) {- // Classes, sizes and a digest prefix only: never the file name, the- // bytes or any decoded text.- deps.logger.info(- {- event: 'attachment_admitted',- channel: normalizedMessage.channelType,- attachmentCount: acceptedAttachmentIds.length,- fileClasses: validated.fileReferences.map(ref => ref.class),- byteLength: validated.fileReferences.reduce((sum, ref) => sum + ref.byteLength, 0),- digestPrefixes: validated.fileReferences.map(ref => ref.digest?.hex.slice(0, 8)),- },- 'Host runtime event'- )- }let acceptedVisualSelection: Record<string, string> | undefinedif (!deps.queueReady()) {@@ -208,14 +207,32 @@ export function createIncomingAdmission(deps: IncomingAdmissionDeps): IncomingAd// 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 || acceptedFileReferenceIds.length)+ const withAcceptedAttachments = (response: MessageResponse): MessageResponse => {+ if (!response.success) return response+ if (validated.fileReferences.length) {+ // Logged once the message is accepted, after every refusal. Classes,+ // sizes and a digest prefix only: never the file name, the bytes or+ // any decoded text.+ deps.logger.info(+ {+ event: 'attachment_admitted',+ channel: normalizedMessage.channelType,+ attachmentCount: acceptedAttachmentIds.length,+ fileClasses: validated.fileReferences.map(ref => ref.class),+ byteLength: validated.fileReferences.reduce((sum, ref) => sum + ref.byteLength, 0),+ digestPrefixes: validated.fileReferences.map(ref => ref.digest?.hex.slice(0, 8)),+ },+ 'Host runtime event'+ )+ }+ return acceptedAttachmentIds.length || acceptedFileReferenceIds.length? {...response,...(acceptedAttachmentIds.length ? { acceptedAttachmentIds } : {}),...(acceptedFileReferenceIds.length ? { acceptedFileReferenceIds } : {}),}: response+ }const dispatchMessage = (): MessageResponse | Promise<MessageResponse> => {const response = deps.dispatch(normalizedMessage, options)return response instanceof Promise@@ -448,7 +465,17 @@ export function createIncomingAdmission(deps: IncomingAdmissionDeps): IncomingAd// 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())+ // Only a GFS reference needs the Host's GFS token.+ const access: FileReferenceGfsAccess = fileReferences.some(ref => ref.source.kind === 'gfs')+ ? deps.fileReferenceGfs()+ : { status: 'unsupported' }+ const resolved: FileReferenceResolutionResult =+ access.status === 'credentials_failed'+ ? { ok: false, failure: 'credentials', errorClass: access.errorClass }+ : await resolveFileReferences(+ fileReferences,+ access.status === 'available' ? access.client : null+ )if (!resolved.ok) {deps.logger.warn({@@ -456,6 +483,8 @@ export function createIncomingAdmission(deps: IncomingAdmissionDeps): IncomingAdchannel: normalizedMessage.channelType,referenceCount: fileReferences.length,failure: resolved.failure,+ errorClass: resolved.errorClass,+ status: resolved.status ?? null,},'Host runtime event')@@ -478,7 +507,7 @@ export function createIncomingAdmission(deps: IncomingAdmissionDeps): IncomingAdreturn admitAndRun()})()- function fileReferenceFailure(failure: 'transient' | 'invalid' | 'contract'): TaskError {+ function fileReferenceFailure(failure: FileReferenceCheckFailure): TaskError {const provider = deps.hostProvider() ?? 'unknown'if (failure === 'invalid')return {@@ -487,12 +516,15 @@ export function createIncomingAdmission(deps: IncomingAdmissionDeps): IncomingAdretryable: false,provider,}+ const messages: Record<Exclude<FileReferenceCheckFailure, 'invalid'>, string> = {+ transient: 'The referenced files could not be checked. Send the message again.',+ contract: 'The file service returned an unexpected answer for a referenced file.',+ credentials:+ 'The Host could not authenticate to the file service to check the referenced files.',+ }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.',+ code: FileReferenceErrorCode.CheckFailed,+ message: messages[failure],retryable: failure === 'transient',provider,}diff --git a/mcp-host/src/core/errors.ts b/mcp-host/src/core/errors.tsindex af1d4cc5b..6a4ba0b9b 100644--- a/mcp-host/src/core/errors.ts+++ b/mcp-host/src/core/errors.ts@@ -86,9 +86,11 @@ export enum FileAttachmentErrorCode {/*** 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.+ * `SchemaVersionUnsupported` and `Invalid` reject the message (terminal).+ * `CheckFailed` rejects it because the Host could not ask gfsc about the+ * references. 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. */@@ -103,6 +105,11 @@ export enum FileReferenceErrorCode {TooLarge = 'FILE_REFERENCE_TOO_LARGE',/** The Host cannot serve this reference (no `gfs.read` scope, or not a GFS source). */Unsupported = 'FILE_REFERENCE_UNSUPPORTED',+ /**+ * gfsc could not be asked, or its answer could not be used: retryable only+ * when the failure was transient (timeout, network, 429, 5xx).+ */+ CheckFailed = 'FILE_REFERENCE_CHECK_FAILED',}export class LlmError extends AgentError {diff --git a/mcp-host/src/internalTools/gfsClient.ts b/mcp-host/src/internalTools/gfsClient.tsindex d68f29896..ce6254e6c 100644--- a/mcp-host/src/internalTools/gfsClient.ts+++ b/mcp-host/src/internalTools/gfsClient.ts@@ -25,28 +25,60 @@ export interface GfsRuntimeEnv {export type GfsToolScope = 'gfs.read' | 'gfs.write'/**- * Read the mounted token only to advertise its supported native tools. This is- * deliberately fail-closed and is not an authorization boundary: gfsc still- * verifies the same bearer token and evaluates the permission store.+ * What the Host's GFS token says about the native tools it can serve.+ * - `not_configured`: no direct token and no token file at the default path.+ * - `token_unreadable`: the configured token file cannot be read, or is empty.+ * - `token_undecodable`: the token is not a JWT with a list of string scopes.+ * - `scope_outside_allowlist`: a scope other than `gfs.read`/`gfs.write`.+ * - `ok`: the scopes, possibly none.+ */+export type GfsToolScopeInspection =+ | { status: 'ok'; scopes: ReadonlySet<GfsToolScope> }+ | { status: 'not_configured' }+ | { status: 'token_unreadable' }+ | { status: 'token_undecodable' }+ | { status: 'scope_outside_allowlist' }++/**+ * Read the mounted token only to learn which native GFS tools it can serve.+ * This is not an authorization boundary: gfsc still verifies the same bearer+ * token and evaluates the permission store.+ */+export function inspectGfsToolScopes(env: GfsRuntimeEnv): GfsToolScopeInspection {+ let token = envValue(env, DIRECT_KEY)+ if (!token) {+ const configuredPath = envValue(env, FILE_KEY)+ try {+ token = (env.readFileSync ?? ((path: string) => readFileSync(path, 'utf8')))(+ configuredPath || DEFAULT_GFS_ACCESS_FILE+ ).trim()+ } catch (error) {+ // Only the default path may be absent: a configured path that cannot be+ // read is a broken mount, not a Host without GFS.+ if (!configuredPath && (error as NodeJS.ErrnoException).code === 'ENOENT')+ return { status: 'not_configured' }+ return { status: 'token_unreadable' }+ }+ if (!token) return { status: 'token_unreadable' }+ }+ const scopes = decodeRuntimeJwtScopes(token)+ if (!scopes) return { status: 'token_undecodable' }+ if (+ !scopes.every((scope): scope is GfsToolScope => scope === 'gfs.read' || scope === 'gfs.write')+ )+ return { status: 'scope_outside_allowlist' }+ return { status: 'ok', scopes: new Set(scopes) }+}++/**+ * The scopes that advertise native GFS tools, or null when there are none.+ * This is deliberately fail-closed: every status other than `ok` with at least+ * one scope is null.*/export function getGfsToolScopes(env: GfsRuntimeEnv): ReadonlySet<GfsToolScope> | null {try {- const direct = envValue(env, DIRECT_KEY)- const token = direct- ? direct- : (env.readFileSync ?? ((path: string) => readFileSync(path, 'utf8')))(- envValue(env, FILE_KEY, DEFAULT_GFS_ACCESS_FILE)- ).trim()- if (!token) return null- const scopes = decodeRuntimeJwtScopes(token)- if (- !scopes ||- scopes.length === 0 ||- !scopes.every((scope): scope is GfsToolScope => scope === 'gfs.read' || scope === 'gfs.write')- ) {- return null- }- return new Set(scopes)+ const inspection = inspectGfsToolScopes(env)+ return inspection.status === 'ok' && inspection.scopes.size > 0 ? inspection.scopes : null} catch {return null}diff --git a/mcp-host/src/main.ts b/mcp-host/src/main.tsindex 0c4218bc4..32edad0c1 100644--- a/mcp-host/src/main.ts+++ b/mcp-host/src/main.ts@@ -18,7 +18,8 @@ import { AgentStateMachine, CronScheduler, wireCronDispatch } from './agent'import type { ResolvedTaskModel } from './agent'import { agentToolEnvProvider } from './agent/agentToolEnv'import type { PendingCronResult } from './agent/cronDispatch'-import { createIncomingAdmission } from './agent/incomingAdmission'+import { createFileReferenceGfsGate } from './agent/fileReferenceGfsGate'+import { createIncomingAdmission, replayedIncomingMessage } from './agent/incomingAdmission'import { INCOMING_ATTACHMENT_MAX_COUNT } from './agent/incomingAttachments'import { IncomingDelivery } from './agent/incomingDelivery'import {@@ -61,7 +62,7 @@ import {resolveGuardrailHookDescriptors,withResolvedHookDescriptors,} from './guardrailHookResolver'-import { createGfscClient, getGfsToolScopes } from './internalTools/gfsClient'+import { createGfscClient, inspectGfsToolScopes } from './internalTools/gfsClient'import { HostWatcher, LlmHookWatcher, getHost, getLlmHook } from './k8sClient'import { StatelessHeartbeat } from './lifecycle/statelessHeartbeat'import { TaskLifecycle } from './lifecycle/taskLifecycle'@@ -1997,11 +1998,7 @@ function handleIncomingMessage(message,messageQueue,() => prepareIncomingMessage(message, options),- () =>- dispatchIncomingMessage(- { ...message, imageModel: undefined, fileReferenceResolutions: undefined },- options- )+ () => dispatchIncomingMessage(replayedIncomingMessage(message), options))}@@ -2009,8 +2006,12 @@ function handleIncomingMessage(// 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 fileReferenceGfsGate = createFileReferenceGfsGate({+ inspectScopes: () => inspectGfsToolScopes(fileReferenceGfsEnv),+ client: createGfscClient(fileReferenceGfsEnv, {+ maxRetryWaitMs: VISUAL_INPUT_LIMITS.validationTimeoutMs,+ }),+ logger,})const prepareIncomingMessage = createIncomingAdmission({@@ -2028,8 +2029,7 @@ const prepareIncomingMessage = createIncomingAdmission({resolveImageInput,applySessionModelSelection,dispatch: dispatchIncomingMessage,- fileReferenceClient: () =>- getGfsToolScopes(fileReferenceGfsEnv)?.has('gfs.read') ? fileReferenceGfscClient : null,+ fileReferenceGfs: fileReferenceGfsGate,logger,})diff --git a/mcp-host/src/server/__tests__/messageRoute.test.ts b/mcp-host/src/server/__tests__/messageRoute.test.tsindex 0515bcd94..dd6c968b5 100644--- a/mcp-host/src/server/__tests__/messageRoute.test.ts+++ b/mcp-host/src/server/__tests__/messageRoute.test.ts@@ -335,7 +335,7 @@ describe('handleMessageRoute — acceptedAttachmentIds through the real admissioresolveImageInput: () => undefined,applySessionModelSelection: vi.fn(),dispatch,- fileReferenceClient: () => null,+ fileReferenceGfs: () => ({ status: 'unsupported' }),logger: { info: vi.fn(), warn: vi.fn() },})return { dispatch, handlers: makeHandlers({ messageHandler }) }@@ -444,7 +444,7 @@ describe('handleMessageRoute — structured file references (#666)', () => {resolveImageInput: () => undefined,applySessionModelSelection: vi.fn(),dispatch,- fileReferenceClient: () => null,+ fileReferenceGfs: () => ({ status: 'unsupported' }),logger: { info: vi.fn(), warn: vi.fn() },})return { dispatch, handlers: makeHandlers({ messageHandler }) }@@ -517,7 +517,7 @@ describe('handleMessageRoute — structured file references (#666)', () => {},'FILE_REFERENCE_INVALID',],- ])('refuses %s with 400 before dispatch', async (_label, value, code) => {+ ])('refuses %s with a 200 MessageResponse 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)@@ -525,7 +525,9 @@ describe('handleMessageRoute — structured file references (#666)', () => {const captured = makeRes()await handleMessageRoute(request(value()), captured.res, handlers)- expect(captured.statusCode).toBe(400)+ // The same status as every other admission refusal: rpc-proxy relays the+ // body only for a 2xx answer.+ expect(captured.statusCode).toBe(200)expect(captured.jsonBody).toEqual({success: false,error: { code, message: expect.any(String), retryable: false, provider: 'unknown' },diff --git a/mcp-host/src/server/routes.ts b/mcp-host/src/server/routes.tsindex 80d430ba3..bf1852cf1 100644--- a/mcp-host/src/server/routes.ts+++ b/mcp-host/src/server/routes.ts@@ -317,13 +317,15 @@ export async function handleMessageRoute(}// Issue #666 — a malformed reference or an unknown schema version refuses- // the whole message: the turn must not run without the file it names.+ // the whole message: the turn must not run without the file it names. The+ // refusal is a 200 `MessageResponse`, like every other admission refusal,+ // so rpc-proxy relays its code instead of reporting a failed upstream.const fileReferences = parseIncomingFileReferences(message.fileReferences,config.fileReferenceMaxCount)if (!fileReferences.ok) {- json(res, 400, {+ json(res, 200, {success: false,error: {code: fileReferences.code,diff --git a/rpc-proxy/package-lock.json b/rpc-proxy/package-lock.jsonindex 24d635091..b4ebe5f81 100644--- a/rpc-proxy/package-lock.json+++ b/rpc-proxy/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-rpc-proxy",- "version": "0.1.91",+ "version": "0.1.92","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-rpc-proxy",- "version": "0.1.91",+ "version": "0.1.92","dependencies": {"cors": "^2.8.5","express": "^4.21.2",diff --git a/rpc-proxy/package.json b/rpc-proxy/package.jsonindex 6b775fd3f..325a2ebfd 100644--- a/rpc-proxy/package.json+++ b/rpc-proxy/package.json@@ -1,6 +1,6 @@{"name": "clerum-rpc-proxy",- "version": "0.1.91",+ "version": "0.1.92","description": "External-facing RPC proxy for tenant-scoped MCP access","main": "dist/main.js","engines": {diff --git a/rpc-proxy/test/routes.rpcHostMessageRefusal.test.ts b/rpc-proxy/test/routes.rpcHostMessageRefusal.test.tsnew file mode 100644index 000000000..16247db5d--- /dev/null+++ b/rpc-proxy/test/routes.rpcHostMessageRefusal.test.ts@@ -0,0 +1,104 @@+/**+ * #666 — the Host answers a refused message with HTTP 200 and a+ * `success:false` MessageResponse. Only the host resolution and the auth are+ * doubles: the real `forwardHostMessageToHost` runs against a fetch double, so+ * the client receives what the proxy's own forwarding produces.+ */+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'+import express from 'express'+import request from 'supertest'+import { createRpcRouter } from '../src/routes/rpc.js'++const authTokenMock = vi.hoisted(() => ({+ verifyRpcToken: vi.fn(),+}))++const resolveHostConnectionForUser = vi.hoisted(() => vi.fn())++vi.mock('../src/authToken.js', () => authTokenMock)+vi.mock('../src/services/mcpProxyService.js', async importOriginal => ({+ ...(await importOriginal<typeof import('../src/services/mcpProxyService.js')>()),+ resolveHostConnectionForUser,+}))++const refusal = {+ success: false,+ error: {+ code: 'FILE_REFERENCE_INVALID',+ message: 'Each file reference must appear once.',+ retryable: false,+ provider: 'unknown',+ },+}++describe('routes/rpc host message refusal (#666)', () => {+ beforeEach(() => {+ authTokenMock.verifyRpcToken.mockReturnValue({+ sub: 'user-1',+ typ: 'user',+ accessScope: 'team',+ teamId: 'team-1',+ scopes: ['host:message:invoke'],+ hostRefs: ['agent2'],+ jti: 'j1',+ iat: 1,+ exp: 9999999999,+ })+ resolveHostConnectionForUser.mockResolvedValue({+ name: 'agent2',+ url: 'http://agent2.mcp-host.svc.cluster.local:8080',+ headers: {},+ })+ })++ afterEach(() => {+ vi.restoreAllMocks()+ })++ function makeApp() {+ const app = express()+ app.use(express.json())+ app.use(createRpcRouter())+ return app+ }++ function hostAnswers(status: number, body: unknown) {+ return vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(+ new Response(JSON.stringify(body), {+ status,+ headers: { 'content-type': 'application/json' },+ })+ )+ }++ const send = () =>+ request(makeApp())+ .post('/rpc/hosts/agent2/messages')+ .set('authorization', 'Bearer token')+ .send({ content: 'summarize', channelType: 'rpc', sender: 'desktop-app' })++ it('relays a 200 FILE_REFERENCE_INVALID refusal to the client unchanged', async () => {+ const fetchMock = hostAnswers(200, refusal)++ const response = await send()++ // Witness: the message reached the Host's runtime endpoint once.+ expect(fetchMock).toHaveBeenCalledTimes(1)+ expect(String(fetchMock.mock.calls[0]![0])).toBe(+ 'http://agent2.mcp-host.svc.cluster.local:8080/v1/runtime/messages'+ )+ expect(response.status).toBe(200)+ expect(response.body).toEqual(refusal)+ })++ it('turns the same refusal into a 502 when the Host answers it with a 400', async () => {+ const fetchMock = hostAnswers(400, refusal)++ const response = await send()++ // Control: this is why the Host answers refusals with 200.+ expect(fetchMock).toHaveBeenCalledTimes(1)+ expect(response.status).toBe(502)+ expect(response.body).toEqual({ error: 'Upstream host unavailable' })+ })+})