Skip to content

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.ts
index 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.json
index 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.json
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.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.')
+ 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.ts
index 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: () => FileReferenceGfsAccess
logger: {
info: (obj: Record<string, unknown>, msg: string) => void
warn: (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> | undefined
if (!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): IncomingAd
channel: 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): IncomingAd
return 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): IncomingAd
retryable: 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 admissio
resolveImageInput: () => 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.ts
index 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.json
index 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.json
index 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.ts
new file mode 100644
index 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' })
+ })
+})