Skip to content

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

TypeScript

fix(files): close the round-7 review items on file reference ingress

Alfredo Lopez3c90e0d2112a
diff --git a/control-ui/package-lock.json b/control-ui/package-lock.json
index 6a11d5f01..112e6816b 100644
--- a/control-ui/package-lock.json
+++ b/control-ui/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-ui",
- "version": "0.1.654",
+ "version": "0.1.655",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-ui",
- "version": "0.1.654",
+ "version": "0.1.655",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/frontend-components": "file:../packages/frontend-components",
@@ -62,7 +62,7 @@
},
"../packages/gfs-interaction-policy": {
"name": "@clerum/gfs-interaction-policy",
- "version": "0.1.0",
+ "version": "0.2.0",
"license": "MIT"
},
"../packages/llm-providers": {
diff --git a/control-ui/package.json b/control-ui/package.json
index 956a113f2..349558be4 100644
--- a/control-ui/package.json
+++ b/control-ui/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-ui",
- "version": "0.1.654",
+ "version": "0.1.655",
"private": true,
"scripts": {
"dev": "NEXT_IGNORE_INCORRECT_LOCKFILE=1 next dev",
diff --git a/desktop-app/package-lock.json b/desktop-app/package-lock.json
index ee981db3f..cd2d09282 100644
--- a/desktop-app/package-lock.json
+++ b/desktop-app/package-lock.json
@@ -65,7 +65,7 @@
},
"../packages/gfs-interaction-policy": {
"name": "@clerum/gfs-interaction-policy",
- "version": "0.1.0",
+ "version": "0.2.0",
"license": "MIT"
},
"node_modules/@adobe/css-tools": {
diff --git a/desktop-app/ui/src/hooks/domain/__tests__/sendAgentMessage.fileReferences.test.tsx b/desktop-app/ui/src/hooks/domain/__tests__/sendAgentMessage.fileReferences.test.tsx
index dba454a73..36f96ecd2 100644
--- a/desktop-app/ui/src/hooks/domain/__tests__/sendAgentMessage.fileReferences.test.tsx
+++ b/desktop-app/ui/src/hooks/domain/__tests__/sendAgentMessage.fileReferences.test.tsx
@@ -18,7 +18,7 @@ let uuidCounter = 0
const RID = '0123456789abcdef0123456789abcdef'
const planFile: ComposerGlobalFileReference = {
- id: `global-file:${RID}`,
+ id: `global-file:main:${RID}`,
type: 'global_file',
resourceId: RID,
drive: 'main',
@@ -109,7 +109,7 @@ const NOT_RECEIVED =
const notesFile: ComposerGlobalFileReference = {
...planFile,
- id: `global-file:${RID.replace('0', 'f')}`,
+ id: `global-file:main:${RID.replace('0', 'f')}`,
resourceId: RID.replace('0', 'f'),
gfsUri: `gfs://main/${RID.replace('0', 'f')}`,
label: 'notes.md',
@@ -151,9 +151,23 @@ function sentReferenceIds(): string[] {
}
/** Proves the accepted-ack branch ran, whatever the ack shape. */
-function expectAcceptedAck(shape: string, pushToast: ReturnType<typeof vi.fn>) {
+function expectAcceptedAck(
+ shape: string,
+ pushToast: ReturnType<typeof vi.fn>,
+ droppedMessage?: string
+) {
if (shape === 'synchronous') {
- expect(pushToast).toHaveBeenCalledWith('Message sent to agent-x.', 'success')
+ if (droppedMessage === undefined) {
+ expect(pushToast).toHaveBeenCalledWith('Message sent to agent-x.', 'success')
+ return
+ }
+ // A send that lost its files shows only the error that says so: a success
+ // toast beside it would contradict it. The error toast is the witness that
+ // the accepted branch ran, and no other error toast may appear with it.
+ expect(pushToast).not.toHaveBeenCalledWith('Message sent to agent-x.', 'success')
+ expect(pushToast.mock.calls.filter(([, kind]) => kind === 'error')).toEqual([
+ [droppedMessage, 'error'],
+ ])
return
}
expect(clerum.chat.appendMessages).toHaveBeenCalledWith(
@@ -173,7 +187,7 @@ describe('sendAgentMessage — references the Host did not receive (#666 M1)', (
expect(result.current.agentError).toBe(NOT_RECEIVED)
expect(spies.pushToast).toHaveBeenCalledWith(NOT_RECEIVED, 'error')
// The send stands: accepted, not failed, and not resent.
- expectAcceptedAck(shape, spies.pushToast)
+ expectAcceptedAck(shape, spies.pushToast, NOT_RECEIVED)
expect(result.current.failedAgentSend).toBeNull()
expect(clerum.rpc.invokeHostMessage).toHaveBeenCalledTimes(1)
}
@@ -206,7 +220,7 @@ describe('sendAgentMessage — references the Host did not receive (#666 M1)', (
'The Host did not receive 1 of the selected Global Files; the message was sent without them.'
expect(result.current.agentError).toBe(partial)
expect(spies.pushToast).toHaveBeenCalledWith(partial, 'error')
- expectAcceptedAck(shape, spies.pushToast)
+ expectAcceptedAck(shape, spies.pushToast, partial)
expect(clerum.rpc.invokeHostMessage).toHaveBeenCalledTimes(1)
}
)
diff --git a/desktop-app/ui/src/hooks/domain/useAgentChatController.ts b/desktop-app/ui/src/hooks/domain/useAgentChatController.ts
index d33944b75..4e8ac35da 100644
--- a/desktop-app/ui/src/hooks/domain/useAgentChatController.ts
+++ b/desktop-app/ui/src/hooks/domain/useAgentChatController.ts
@@ -2789,6 +2789,7 @@ export function useAgentChatController({
// and still accepts the message. The ack lists the reference ids the
// Host admitted; a sent id missing from it never reached the Host. The
// send itself stands and is not retried.
+ let fileReferencesDropped = false
if (ackOk && fileReferences.length > 0) {
const acceptedFileReferenceIds = new Set<string>(
Array.isArray(response.acceptedFileReferenceIds)
@@ -2799,6 +2800,7 @@ export function useAgentChatController({
reference => !acceptedFileReferenceIds.has(reference.id)
)
if (droppedFiles.length > 0) {
+ fileReferencesDropped = true
const droppedMessage =
droppedFiles.length === fileReferences.length
? FILE_REFERENCES_NOT_RECEIVED_MESSAGE
@@ -2887,7 +2889,9 @@ export function useAgentChatController({
status: previous.events.length ? 'completed' : 'no_activity',
errorMessage: undefined,
}))
- pushToast(`Message sent to ${sendAgent}.`, 'success')
+ // The dropped-files error above already told the user what happened;
+ // a success toast right after it would contradict it.
+ if (!fileReferencesDropped) pushToast(`Message sent to ${sendAgent}.`, 'success')
}
activityInFlightByAgentRef.current[sendAgent] = (
activityInFlightByAgentRef.current[sendAgent] || []
diff --git a/desktop-app/ui/src/lib/__tests__/composerReferencesPrompt.test.ts b/desktop-app/ui/src/lib/__tests__/composerReferencesPrompt.test.ts
index 0d4b724cd..2ee7d52e4 100644
--- a/desktop-app/ui/src/lib/__tests__/composerReferencesPrompt.test.ts
+++ b/desktop-app/ui/src/lib/__tests__/composerReferencesPrompt.test.ts
@@ -50,6 +50,8 @@ describe('composer references prompt helpers', () => {
expect(prompt).toContain('Connectors: "github"')
expect(prompt).toContain('prefix before "__" exactly matches')
expect(prompt).toContain('Agent Files: "assets/invite.png"')
+ // The quoted names are declared as JSON literals so the model passes them decoded.
+ expect(prompt).toContain('Every quoted name below is a JSON string literal')
expect(prompt).toContain('clerum__context_files_read')
// The Global Files line names the selection; the read instruction now comes
// from the Host's turn context for the structured fileReferences (#666).
diff --git a/desktop-app/ui/src/lib/composerReferencesPrompt.ts b/desktop-app/ui/src/lib/composerReferencesPrompt.ts
index 83e067cac..2d6822007 100644
--- a/desktop-app/ui/src/lib/composerReferencesPrompt.ts
+++ b/desktop-app/ui/src/lib/composerReferencesPrompt.ts
@@ -81,7 +81,7 @@ export function buildComposerReferencesPromptSection(
}
const lines = [
- 'USER-ATTACHED CONTEXT: The user selected these capabilities/files for this message. Prefer them when they are relevant to the request.',
+ 'USER-ATTACHED CONTEXT: The user selected these capabilities/files for this message. Prefer them when they are relevant to the request. Every quoted name below is a JSON string literal: pass its decoded value, without the surrounding quotes or escapes, when you use it in a tool call.',
]
if (plugins.length) {
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 7da4bd368..02562bddf 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.469",
+ "version": "0.1.470",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.469",
+ "version": "0.1.470",
"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 b67c0c99f..da609b1ab 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.469",
+ "version": "0.1.470",
"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
index 61e342467..2dd9a4703 100644
--- a/mcp-host/src/agent/__tests__/fileReferenceGfsGate.test.ts
+++ b/mcp-host/src/agent/__tests__/fileReferenceGfsGate.test.ts
@@ -7,11 +7,16 @@ import type { GfsToolScopeInspection } from '../../internalTools/gfsClient'
import { createFileReferenceGfsGate } from '../fileReferenceGfsGate'
import type { FileReferenceGfscClient } from '../fileReferenceResolver'
-function gate(inspection: GfsToolScopeInspection) {
+function gate(inspection: GfsToolScopeInspection, approvalTools?: Record<string, boolean>) {
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 })
+ const access = createFileReferenceGfsGate({
+ inspectScopes,
+ approvalTools: () => approvalTools,
+ client,
+ logger,
+ })
return { access, client, logger, inspectScopes }
}
@@ -52,6 +57,38 @@ describe('createFileReferenceGfsGate (#666)', () => {
expect(logger.error).not.toHaveBeenCalled()
})
+ it.each(['clerum__gfs_stat', 'clerum__gfs_resolve', 'clerum__gfs_read'])(
+ 'answers unsupported when approval.tools forces %s to approval, before asking gfsc',
+ tool => {
+ const { access, logger, inspectScopes } = gate(
+ { status: 'ok', scopes: new Set(['gfs.read']) },
+ { [tool]: true }
+ )
+ expect(access()).toEqual({ status: 'unsupported' })
+ expect(logger.warn).toHaveBeenCalledWith(
+ { event: 'file_reference_gfs_unavailable', reason: 'read_tool_requires_approval' },
+ 'Host runtime event'
+ )
+ // Witness: the decision came from the approval override, not the token.
+ expect(inspectScopes).not.toHaveBeenCalled()
+ }
+ )
+
+ it.each([
+ ['an override that waives approval', { clerum__gfs_read: false }],
+ ['an override on a tool admission does not use', { clerum__gfs_write: true }],
+ ['no overrides at all', undefined],
+ ])('keeps the client available with %s', (_label, approvalTools) => {
+ const { access, client, logger, inspectScopes } = gate(
+ { status: 'ok', scopes: new Set(['gfs.read']) },
+ approvalTools
+ )
+ expect(access()).toEqual({ status: 'available', client })
+ // Witness: the token was inspected, so the approval check let the message through.
+ expect(inspectScopes).toHaveBeenCalledTimes(1)
+ expect(logger.warn).not.toHaveBeenCalled()
+ })
+
it.each([
['token_unreadable', 'TokenReadError'],
['token_undecodable', 'TokenDecodeError'],
diff --git a/mcp-host/src/agent/__tests__/incomingAttachments.test.ts b/mcp-host/src/agent/__tests__/incomingAttachments.test.ts
index 88cd5a8bc..f15fdeb97 100644
--- a/mcp-host/src/agent/__tests__/incomingAttachments.test.ts
+++ b/mcp-host/src/agent/__tests__/incomingAttachments.test.ts
@@ -1,6 +1,10 @@
import { describe, expect, it } from 'vitest'
import { createHash } from 'node:crypto'
-import { INCOMING_ATTACHMENT_MAX_COUNT, validateIncomingAttachments } from '../incomingAttachments'
+import {
+ FILE_ATTACHMENT_MIME_TYPE_MAX_LENGTH,
+ INCOMING_ATTACHMENT_MAX_COUNT,
+ validateIncomingAttachments,
+} from '../incomingAttachments'
// The #669 image cases below are unchanged. They moved with the validator and
// now also pass the file options (issue #666), which the image branch never reads.
@@ -445,6 +449,26 @@ describe('file attachment validation (issue #666)', () => {
)
})
+ it('refuses a declared media type longer than the bound', () => {
+ const atBound = 'a'.repeat(FILE_ATTACHMENT_MIME_TYPE_MAX_LENGTH)
+ // Witness: a type exactly at the bound is admitted, so the refusal below
+ // comes from the length check and not from another rule.
+ expect(admitOne({ ...notes, mimeType: atBound }).attachment).toMatchObject({
+ mimeType: atBound,
+ })
+ const tooLong = validateIncomingAttachments(
+ [{ ...notes, mimeType: 'a'.repeat(FILE_ATTACHMENT_MIME_TYPE_MAX_LENGTH + 1) }],
+ limits
+ )
+ expect(tooLong).toMatchObject({
+ ok: false,
+ error: { code: 'FILE_ATTACHMENT_INVALID', retryable: false },
+ })
+ expect(tooLong.ok === false && tooLong.error.message).toBe(
+ 'A file attachment declares a media type that is too long.'
+ )
+ })
+
it('names the list requirement when attachments are not a list', () => {
expect(validateIncomingAttachments('not-a-list', limits)).toEqual({
ok: false,
diff --git a/mcp-host/src/agent/__tests__/sourceMessageForResume.test.ts b/mcp-host/src/agent/__tests__/sourceMessageForResume.test.ts
index 633ad5251..6de0755e7 100644
--- a/mcp-host/src/agent/__tests__/sourceMessageForResume.test.ts
+++ b/mcp-host/src/agent/__tests__/sourceMessageForResume.test.ts
@@ -89,6 +89,57 @@ describe('sourceMessageForResume (#666 R4-M2)', () => {
expect(resumed?.messageId).toBe('message-1')
})
+ it('persists only the fields a restart reads, not the raw channel payload', () => {
+ const message = {
+ ...sourceMessage([]),
+ threadId: 'thread-1',
+ imageModel: { provider: 'openai', model: 'gpt-image' },
+ metadata: { teamId: 'team-1', slackBotToken: 'SENTINEL-666-raw-metadata' },
+ providerIdentity: { provider: 'SENTINEL-666-identity' },
+ traceContext: { traceparent: 'SENTINEL-666-trace' },
+ model: { provider: 'SENTINEL-666-model', model: 'm' },
+ modelSelectionRevision: 7,
+ fileReferences: [{ id: 'SENTINEL-666-reference' }],
+ } as unknown as IncomingMessage
+ const resumed = sourceMessageForResume(message)
+ // Liveness witness: what a restart reads is still there.
+ expect(resumed).toMatchObject({
+ content: 'Read the attached notes',
+ sender: 'user-1',
+ channelType: 'rpc',
+ channelId: 'chatllm',
+ threadId: 'thread-1',
+ hostRef: 'chatllm',
+ messageId: 'message-1',
+ imageModel: { provider: 'openai', model: 'gpt-image' },
+ metadata: { teamId: 'team-1' },
+ })
+ expect(resumed?.fileReferenceResolutions).toHaveLength(1)
+ expect(Object.keys(resumed ?? {}).sort()).toEqual([
+ 'channelId',
+ 'channelType',
+ 'content',
+ 'fileReferenceResolutions',
+ 'hostRef',
+ 'imageModel',
+ 'messageId',
+ 'metadata',
+ 'sender',
+ 'threadId',
+ 'timestamp',
+ ])
+ expect(JSON.stringify(resumed)).not.toContain('SENTINEL-666')
+ })
+
+ it('drops metadata that carries no team scope', () => {
+ const resumed = sourceMessageForResume({
+ ...sourceMessage([]),
+ metadata: { slackBotToken: 'SENTINEL-666-raw-metadata' },
+ })
+ expect(resumed?.content).toBe('Read the attached notes')
+ expect(resumed).not.toHaveProperty('metadata')
+ })
+
it('returns undefined without a source message', () => {
expect(sourceMessageForResume(undefined)).toBeUndefined()
})
diff --git a/mcp-host/src/agent/fileReferenceGfsGate.ts b/mcp-host/src/agent/fileReferenceGfsGate.ts
index f1030e14d..f4de80791 100644
--- a/mcp-host/src/agent/fileReferenceGfsGate.ts
+++ b/mcp-host/src/agent/fileReferenceGfsGate.ts
@@ -7,6 +7,10 @@
* 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.
+ *
+ * Admission asks gfsc under the Host's own token, so it must not learn what an
+ * operator gated behind approval: when `approval.tools` forces a GFS read tool
+ * to approval, the references are admitted as `unsupported` too.
*/
import type { GfsToolScopeInspection } from '../internalTools/gfsClient'
import type { FileReferenceGfscClient } from './fileReferenceResolver'
@@ -16,8 +20,17 @@ export type FileReferenceGfsAccess =
| { status: 'unsupported' }
| { status: 'credentials_failed'; errorClass: 'TokenReadError' | 'TokenDecodeError' }
+/** The GFS tools whose answers admission would otherwise hand out unapproved. */
+export const FILE_REFERENCE_GFS_READ_TOOLS = [
+ 'clerum__gfs_stat',
+ 'clerum__gfs_resolve',
+ 'clerum__gfs_read',
+] as const
+
export interface FileReferenceGfsGateDeps {
inspectScopes: () => GfsToolScopeInspection
+ /** The effective `approval.tools` overrides, read per message. */
+ approvalTools: () => Readonly<Record<string, boolean>> | undefined
client: FileReferenceGfscClient
logger: {
warn: (obj: Record<string, unknown>, msg: string) => void
@@ -29,6 +42,17 @@ export function createFileReferenceGfsGate(
deps: FileReferenceGfsGateDeps
): () => FileReferenceGfsAccess {
return () => {
+ const tools = deps.approvalTools()
+ const gatedTool = tools
+ ? FILE_REFERENCE_GFS_READ_TOOLS.find(name => Object.hasOwn(tools, name) && tools[name])
+ : undefined
+ if (gatedTool) {
+ deps.logger.warn(
+ { event: 'file_reference_gfs_unavailable', reason: 'read_tool_requires_approval' },
+ 'Host runtime event'
+ )
+ return { status: 'unsupported' }
+ }
const inspection = deps.inspectScopes()
if (inspection.status === 'ok' && inspection.scopes.has('gfs.read'))
return { status: 'available', client: deps.client }
diff --git a/mcp-host/src/agent/incomingAttachments.ts b/mcp-host/src/agent/incomingAttachments.ts
index 90981e112..34d584505 100644
--- a/mcp-host/src/agent/incomingAttachments.ts
+++ b/mcp-host/src/agent/incomingAttachments.ts
@@ -26,6 +26,13 @@ import type { TaskError } from '../queue/types'
*/
export const INCOMING_ATTACHMENT_MAX_COUNT = 20
+/**
+ * Longest media type a file attachment may declare. RFC 6838 caps a type/subtype
+ * pair at 127 + 1 + 127 characters; the declaration reaches the persisted
+ * message and the turn context, so it is bounded like the file name.
+ */
+export const FILE_ATTACHMENT_MIME_TYPE_MAX_LENGTH = 255
+
export type IncomingAttachmentValidation =
| { ok: true; attachments: Attachment[] | undefined; fileReferences: FileReferenceV1[] }
| { ok: false; error: TaskError }
@@ -141,6 +148,8 @@ function validateFile(item: Record<string, unknown>, limits: IncomingAttachmentL
) {
return rejectFile('A file attachment is malformed. Attach the original file again.')
}
+ if (item.mimeType.length > FILE_ATTACHMENT_MIME_TYPE_MAX_LENGTH)
+ return rejectFile('A file attachment declares a media type that is too long.')
const data = item.dataBase64
const tooLarge = taskError(
FileAttachmentErrorCode.TooLarge,
diff --git a/mcp-host/src/agent/sourceMessageForResume.ts b/mcp-host/src/agent/sourceMessageForResume.ts
index 9caeca9f6..2a86599d7 100644
--- a/mcp-host/src/agent/sourceMessageForResume.ts
+++ b/mcp-host/src/agent/sourceMessageForResume.ts
@@ -2,19 +2,45 @@ import type { Attachment, ResumeFileAttachment, ResumeSourceMessage } from '../c
import type { IncomingMessage } from '../server'
/**
- * #666 R4-M2 — the metadata a cold restart needs to rebuild the turn's
- * file-reference pins and attachment lines: identity, resolutions and
- * file-attachment metadata. Image attachments are dropped (their content lives
- * in the frozen snapshot) and inline bytes (dataBase64) never persist.
+ * #666 R4-M2 — what a cold restart needs from the suspended turn's message, and
+ * nothing else. Each field is read after a restart:
+ *
+ * - `sender`, `channelType`, `channelId`, `threadId`: the approval binding, the
+ * workspace root, `session_search`, `cron_manage` ownership and the rpc scope.
+ * - `metadata.teamId`: rpc team scope and budget attribution.
+ * - `content`: the provider-workflow access gate and the tool registry.
+ * - `hostRef`, `messageId`, `timestamp`: Host attribution and the pins' identity.
+ * - `imageModel`: the visual model the turn was pinned to.
+ * - file attachments (metadata) and `fileReferenceResolutions`: the version pins
+ * and attachment lines. Image attachments are dropped (their content lives in
+ * the frozen snapshot) and inline bytes (dataBase64) never persist.
+ *
+ * Everything else the channel delivered (the raw Slack, email or Telegram
+ * payload in `metadata`, `providerIdentity`, `traceContext`, the model piggyback)
+ * is not persisted: an allowlist keeps a field added to the message later out of
+ * the durable row until a restart actually needs it.
*/
export function sourceMessageForResume(
message: IncomingMessage | undefined
): ResumeSourceMessage | undefined {
if (!message) return undefined
const files = message.attachments?.filter(attachment => attachment.kind === 'file') ?? []
+ const teamId = message.metadata?.teamId
return {
- ...message,
- attachments: files.length ? files.map(fileWithoutBytes) : undefined,
+ content: message.content,
+ channelType: message.channelType,
+ channelId: message.channelId,
+ sender: message.sender,
+ timestamp: message.timestamp,
+ messageId: message.messageId,
+ hostRef: message.hostRef,
+ ...(message.threadId !== undefined ? { threadId: message.threadId } : {}),
+ ...(typeof teamId === 'string' ? { metadata: { teamId } } : {}),
+ ...(message.imageModel ? { imageModel: message.imageModel } : {}),
+ ...(files.length ? { attachments: files.map(fileWithoutBytes) } : {}),
+ ...(message.fileReferenceResolutions
+ ? { fileReferenceResolutions: message.fileReferenceResolutions }
+ : {}),
}
}
diff --git a/mcp-host/src/core/conversation/persistence/__tests__/sourceMessageResumeRoundTrip.test.ts b/mcp-host/src/core/conversation/persistence/__tests__/sourceMessageResumeRoundTrip.test.ts
index 424c5c6cc..2a9dd99b1 100644
--- a/mcp-host/src/core/conversation/persistence/__tests__/sourceMessageResumeRoundTrip.test.ts
+++ b/mcp-host/src/core/conversation/persistence/__tests__/sourceMessageResumeRoundTrip.test.ts
@@ -5,7 +5,9 @@
* a hand-written fixture.
*/
import { afterEach, describe, expect, it } from 'vitest'
+import { createHash } from 'node:crypto'
import { buildGfsFileReference, classifyBytes } from '@clerum/gfs-interaction-policy'
+import { validateIncomingAttachments } from '../../../../agent/incomingAttachments'
import { sourceMessageForResume } from '../../../../agent/sourceMessageForResume'
import { prepareStatements } from '../../../../db/statements'
import type { PendingApprovalRow } from '../../../../db/worker/protocol'
@@ -104,6 +106,74 @@ describe('#666 R4-M2 — source message resume round-trip', () => {
// it only proves the column stores what it is given.
})
+ it('persists a really admitted file: reference, digest and detected type survive, bytes and raw payload do not', async () => {
+ const bytes = Buffer.from('SENTINEL-666-admitted-bytes')
+ const admission = validateIncomingAttachments(
+ [
+ {
+ id: 'file-1',
+ kind: 'file',
+ mimeType: 'text/plain',
+ detectedMediaType: 'text/plain',
+ encoding: 'base64',
+ dataBase64: bytes.toString('base64'),
+ filename: 'notes.txt',
+ sizeBytes: bytes.length,
+ digest: { algorithm: 'sha256', hex: createHash('sha256').update(bytes).digest('hex') },
+ },
+ ],
+ { maxCount: 20, maxBytes: 1_000_000, maxFileBytes: 3_145_728, messageId: 'message-real' }
+ )
+ if (!admission.ok) throw new Error(`fixture rejected: ${admission.error.code}`)
+
+ handle = makeSqliteStore()
+ const manager = new ConversationManager(handle.store)
+ const conv = await manager.getOrCreate(SESSION_KEY)
+ await manager.startTurn(conv, 'read the notes', 'task-real')
+ const incoming = {
+ content: 'read the notes',
+ channelType: 'rpc',
+ channelId: 'chatllm',
+ sender: 'user-1',
+ timestamp: '2026-09-29T10:00:00Z',
+ messageId: 'message-real',
+ hostRef: 'chatllm',
+ attachments: admission.attachments,
+ metadata: { teamId: 'team-1', raw: 'SENTINEL-666-raw-metadata' },
+ providerIdentity: { provider: 'SENTINEL-666-identity' },
+ } as unknown as Parameters<typeof sourceMessageForResume>[0]
+ await handle.store.persistSuspend(conv, {
+ request_id: 'req-real',
+ tool_name: 'internal__do',
+ parameters: {},
+ description: 'Approve internal__do',
+ tool_call_id: 'call-real',
+ context_snapshot: [],
+ sourceMessage: sourceMessageForResume(incoming),
+ task_budget: {
+ elapsedActiveMs: 0,
+ iterationsUsed: 1,
+ durationMs: 86400000,
+ maxIterations: 1000,
+ },
+ })
+
+ const s = prepareStatements(handle.worker.db)
+ const row = s.selectPendingApprovalBySession.get(conv.id) as PendingApprovalRow
+ // Liveness witness: the column was written and holds the message.
+ expect(row.source_message).toContain('read the notes')
+ expect(row.source_message).not.toContain(bytes.toString('base64'))
+ expect(row.source_message).not.toContain('SENTINEL-666')
+ const resumed = reconstructPendingApproval(row).sourceMessage
+ expect(resumed?.metadata).toEqual({ teamId: 'team-1' })
+ const [file] = resumed?.attachments ?? []
+ expect(file).toMatchObject({ id: 'file-1', kind: 'file', filename: 'notes.txt' })
+ expect(file?.fileReference?.id).toBe(admission.attachments?.[0]?.fileReference?.id)
+ expect(file?.digest?.hex).toBe(admission.attachments?.[0]?.digest?.hex)
+ expect(file?.detectedMediaType).toBe('text/plain')
+ expect(file).not.toHaveProperty('dataBase64')
+ })
+
it('rebuilds the file version pins on the cold-start listing without the attachment bytes', async () => {
const built = buildGfsFileReference({
drive: 'main',
diff --git a/mcp-host/src/core/orchestration/__tests__/turnContext.test.ts b/mcp-host/src/core/orchestration/__tests__/turnContext.test.ts
index 9e991ba8e..7ca55fb9e 100644
--- a/mcp-host/src/core/orchestration/__tests__/turnContext.test.ts
+++ b/mcp-host/src/core/orchestration/__tests__/turnContext.test.ts
@@ -306,11 +306,11 @@ describe('referenced_file lines (issue #666)', () => {
'referenced_file: id="gfs:main:0000000000000000000000000000000a@v3" name="plan.md" source=gfs drive="main" resourceId="0000000000000000000000000000000a" version=3 class=markdown bytes=120 availability=available\n' +
'referenced_file: id="gfs:main:0000000000000000000000000000000b@v1" name="old.md" source=gfs drive="main" resourceId="0000000000000000000000000000000b" version=1 class=markdown bytes=120 availability=stale code=FILE_REFERENCE_STALE current_version=4\n' +
`referenced_file: id="att:message-0:file-9@sha256:${'c'.repeat(64)}" name="earlier.txt" source=attachment class=text bytes=8 availability=unsupported code=FILE_REFERENCE_UNSUPPORTED\n` +
- "If the user's request refers to a referenced file, read it with clerum__gfs_read using its drive and resourceId. The Host pins each referenced file to its listed version; pass expectedVersion only to read the current_version of a stale reference. clerum__gfs_stat, clerum__gfs_resolve and clerum__gfs_list report the live file, so their version can be newer than the one listed here; clerum__gfs_read still reads the listed version, and a newer one is not readable in this turn unless the reference is stale. A referenced file whose availability is neither available nor stale cannot be read in this turn; tell the user why instead of guessing.\n" +
+ "If the user's request refers to a referenced file, read it with clerum__gfs_read using its drive and resourceId. The Host pins each referenced file to its listed version; pass expectedVersion only to read the current_version of a stale reference. clerum__gfs_stat, clerum__gfs_resolve and clerum__gfs_list report the live file, so their version can be newer than the one listed here; clerum__gfs_read reads the listed version, and reads a newer one only once the reference is stale. A referenced file whose availability is neither available nor stale cannot be read in this turn; tell the user why instead of guessing.\n" +
'</turn-context>\n\n'
)
expect(REFERENCED_FILES_INSTRUCTION).toBe(
- "If the user's request refers to a referenced file, read it with clerum__gfs_read using its drive and resourceId. The Host pins each referenced file to its listed version; pass expectedVersion only to read the current_version of a stale reference. clerum__gfs_stat, clerum__gfs_resolve and clerum__gfs_list report the live file, so their version can be newer than the one listed here; clerum__gfs_read still reads the listed version, and a newer one is not readable in this turn unless the reference is stale. A referenced file whose availability is neither available nor stale cannot be read in this turn; tell the user why instead of guessing."
+ "If the user's request refers to a referenced file, read it with clerum__gfs_read using its drive and resourceId. The Host pins each referenced file to its listed version; pass expectedVersion only to read the current_version of a stale reference. clerum__gfs_stat, clerum__gfs_resolve and clerum__gfs_list report the live file, so their version can be newer than the one listed here; clerum__gfs_read reads the listed version, and reads a newer one only once the reference is stale. A referenced file whose availability is neither available nor stale cannot be read in this turn; tell the user why instead of guessing."
)
})
diff --git a/mcp-host/src/core/orchestration/turnContext.ts b/mcp-host/src/core/orchestration/turnContext.ts
index 5a75557df..b3a14757a 100644
--- a/mcp-host/src/core/orchestration/turnContext.ts
+++ b/mcp-host/src/core/orchestration/turnContext.ts
@@ -80,7 +80,7 @@ export const ATTACHED_FILES_INSTRUCTION =
"If the user's request refers to an attached file, read it with clerum__attachment_read before answering. Files with reader=none cannot be read in this turn; say so instead of guessing."
export const REFERENCED_FILES_INSTRUCTION =
- "If the user's request refers to a referenced file, read it with clerum__gfs_read using its drive and resourceId. The Host pins each referenced file to its listed version; pass expectedVersion only to read the current_version of a stale reference. clerum__gfs_stat, clerum__gfs_resolve and clerum__gfs_list report the live file, so their version can be newer than the one listed here; clerum__gfs_read still reads the listed version, and a newer one is not readable in this turn unless the reference is stale. A referenced file whose availability is neither available nor stale cannot be read in this turn; tell the user why instead of guessing."
+ "If the user's request refers to a referenced file, read it with clerum__gfs_read using its drive and resourceId. The Host pins each referenced file to its listed version; pass expectedVersion only to read the current_version of a stale reference. clerum__gfs_stat, clerum__gfs_resolve and clerum__gfs_list report the live file, so their version can be newer than the one listed here; clerum__gfs_read reads the listed version, and reads a newer one only once the reference is stale. A referenced file whose availability is neither available nor stale cannot be read in this turn; tell the user why instead of guessing."
// Client-supplied values are written with quotePromptValue, which keeps each
// one on its own line and inside its own field. Values the Host computed
diff --git a/mcp-host/src/core/types.ts b/mcp-host/src/core/types.ts
index 799d1fce4..922967561 100644
--- a/mcp-host/src/core/types.ts
+++ b/mcp-host/src/core/types.ts
@@ -152,7 +152,21 @@ export type ResumeFileAttachment = Omit<Attachment, 'dataBase64'> & { kind: 'fil
* attachments are dropped (their content lives in the frozen snapshot) and
* inline file bytes (dataBase64) never persist.
*/
-export type ResumeSourceMessage = Omit<HostIncomingMessage, 'attachments'> & {
+export type ResumeSourceMessage = Pick<
+ HostIncomingMessage,
+ | 'content'
+ | 'channelType'
+ | 'channelId'
+ | 'sender'
+ | 'timestamp'
+ | 'messageId'
+ | 'hostRef'
+ | 'threadId'
+ | 'imageModel'
+ | 'fileReferenceResolutions'
+> & {
+ /** Only the team scope survives; the channel's raw payload is not persisted. */
+ metadata?: { teamId: string }
attachments?: ResumeFileAttachment[]
}
diff --git a/mcp-host/src/internalTools/gfsContentRead.expectedVersion.test.ts b/mcp-host/src/internalTools/gfsContentRead.expectedVersion.test.ts
index 7603a4086..7f061162e 100644
--- a/mcp-host/src/internalTools/gfsContentRead.expectedVersion.test.ts
+++ b/mcp-host/src/internalTools/gfsContentRead.expectedVersion.test.ts
@@ -3,7 +3,7 @@
* was taken at: a different metadata snapshot fails before any content request.
*/
import { describe, expect, it, vi } from 'vitest'
-import { VisualInputBudget } from '../visualInput/policy'
+import { VISUAL_INPUT_LIMITS, VisualInputBudget } from '../visualInput/policy'
import { readGfsContent } from './gfsContentRead'
const FILE_ID = '1234567890abcdef1234567890abcdef'
@@ -11,7 +11,7 @@ const FILE_URI = `gfs://main/${FILE_ID}`
const READ_ARGS = { drive: 'main', resourceId: FILE_ID }
const SENTINEL = Buffer.from('SENTINEL-666-gfs-version')
-function harness(version: number) {
+function harness(version: number, snapshot: { kind?: string; bytes?: number } = {}) {
const request = vi.fn(async (path: string, _init: RequestInit, _deadlineMs: number) => {
if (!path.includes('/content?'))
return new Response(
@@ -22,10 +22,10 @@ function harness(version: number) {
rid: FILE_ID,
drive: 'main',
gfsUri: FILE_URI,
- kind: 'file',
+ kind: snapshot.kind ?? 'file',
name: 'notes.txt',
version,
- bytes: SENTINEL.length,
+ bytes: snapshot.bytes ?? SENTINEL.length,
},
}),
{ headers: { 'content-type': 'application/json' } }
@@ -75,6 +75,29 @@ describe('readGfsContent expectedVersion (#666)', () => {
}
)
+ it.each([
+ ['grew past the file limit', { bytes: VISUAL_INPUT_LIMITS.fileBytes + 1 }, 'limit_exceeded'],
+ ['became a directory', { kind: 'directory' }, 'unsupported_format'],
+ ])(
+ 'reports a pinned read as version_conflict when the newer version %s',
+ async (_name, snapshot, unpinnedCode) => {
+ // Witness: without the pin the same snapshot is refused for its own
+ // reason, so the pinned result below comes from the version check running
+ // first and not from the snapshot being acceptable.
+ const unpinned = harness(4, snapshot)
+ await expect(
+ readGfsContent(unpinned.request, READ_ARGS, { budget: unpinned.budget })
+ ).rejects.toMatchObject({ code: unpinnedCode })
+
+ const pinned = harness(4, snapshot)
+ await expect(
+ readGfsContent(pinned.request, READ_ARGS, { budget: pinned.budget, expectedVersion: 3 })
+ ).rejects.toMatchObject({ code: 'version_conflict' })
+ expect(pinned.metadataRequests()).toBe(1)
+ expect(pinned.contentRequests()).toBe(0)
+ }
+ )
+
it('reads any version when no expectedVersion is given', async () => {
const { request, contentRequests, budget } = harness(7)
const result = await readGfsContent(request, READ_ARGS, { budget })
diff --git a/mcp-host/src/internalTools/gfsContentRead.ts b/mcp-host/src/internalTools/gfsContentRead.ts
index b84bacb9e..101b924f5 100644
--- a/mcp-host/src/internalTools/gfsContentRead.ts
+++ b/mcp-host/src/internalTools/gfsContentRead.ts
@@ -91,7 +91,8 @@ export function normalizeRid(value: unknown): string | null {
function metadataSnapshot(
bytes: Buffer,
- args: { drive: string; resourceId: string }
+ args: { drive: string; resourceId: string },
+ expectedVersion?: number
): { source: GfsImageSource; size: number } {
let envelope: { ok?: unknown; data?: unknown }
try {
@@ -118,6 +119,11 @@ function metadataSnapshot(
(data.bytes as number) < 0
)
throw new VisualInputError('invalid_response')
+ // A pinned read is stale as soon as the version differs, whatever else changed
+ // with it: a newer version that grew past the limit or became a directory is
+ // still reported as the version conflict the tool promises.
+ if (expectedVersion !== undefined && data.version !== expectedVersion)
+ throw new VisualInputError('version_conflict')
if (data.kind !== 'file') throw new VisualInputError('unsupported_format')
if ((data.bytes as number) > VISUAL_INPUT_LIMITS.fileBytes)
throw new VisualInputError('limit_exceeded')
@@ -197,17 +203,13 @@ export async function readGfsContent(
await requireOk(metadata, signal)
snapshot = metadataSnapshot(
await collect(metadata, VISUAL_INPUT_LIMITS.metadataBytes, signal),
- args
+ args,
+ options.expectedVersion
)
} finally {
metadataReservation.release()
}
if (signal.aborted) throw new VisualInputError('cancelled')
- if (
- options.expectedVersion !== undefined &&
- snapshot.source.version !== options.expectedVersion
- )
- throw new VisualInputError('version_conflict')
if (snapshot.size > budget.remainingReadBytes) throw new VisualInputError('limit_exceeded')
// The source snapshot provides an exact bound: chunks and concatenation can
// coexist, so reserve twice that size before beginning the content request.
diff --git a/mcp-host/src/main.ts b/mcp-host/src/main.ts
index 32edad0c1..626e87ae4 100644
--- a/mcp-host/src/main.ts
+++ b/mcp-host/src/main.ts
@@ -2008,6 +2008,7 @@ function handleIncomingMessage(
const fileReferenceGfsEnv = { get: (key: string): string | undefined => process.env[key] }
const fileReferenceGfsGate = createFileReferenceGfsGate({
inspectScopes: () => inspectGfsToolScopes(fileReferenceGfsEnv),
+ approvalTools: () => (currentHost?.spec.approval || config.approvalConfig)?.tools,
client: createGfscClient(fileReferenceGfsEnv, {
maxRetryWaitMs: VISUAL_INPUT_LIMITS.validationTimeoutMs,
}),
diff --git a/packages/gfs-interaction-policy/fileClassifier.test.cjs b/packages/gfs-interaction-policy/fileClassifier.test.cjs
index 00f4b2f60..736b34313 100644
--- a/packages/gfs-interaction-policy/fileClassifier.test.cjs
+++ b/packages/gfs-interaction-policy/fileClassifier.test.cjs
@@ -81,11 +81,14 @@ describe('classifyBytes', () => {
})
describe('isomorphic module', () => {
- it('uses no Node-only API, so the renderer can load it', () => {
- const source = fs.readFileSync(path.join(__dirname, 'fileClassifier.cjs'), 'utf8')
- assert.match(source, /TextDecoder/, 'the module source was not read')
- assert.doesNotMatch(source, /\bBuffer\b/)
- assert.doesNotMatch(source, /require\(['"]node:/)
- assert.doesNotMatch(source, /require\(['"](?:crypto|fs|path|zlib)['"]\)/)
- })
+ // The renderer loads all three modules (index.cjs re-exports the other two).
+ for (const file of ['fileClassifier.cjs', 'fileReference.cjs', 'index.cjs']) {
+ it(`${file} uses no Node-only API, so the renderer can load it`, () => {
+ const source = fs.readFileSync(path.join(__dirname, file), 'utf8')
+ assert.match(source, /module\.exports/, `the ${file} source was not read`)
+ assert.doesNotMatch(source, /\bBuffer\b/)
+ assert.doesNotMatch(source, /require\(['"]node:/)
+ assert.doesNotMatch(source, /require\(['"](?:crypto|fs|path|zlib)['"]\)/)
+ })
+ }
})
diff --git a/packages/gfs-interaction-policy/fileReference.cjs b/packages/gfs-interaction-policy/fileReference.cjs
index 5adea4c34..aee85bb3e 100644
--- a/packages/gfs-interaction-policy/fileReference.cjs
+++ b/packages/gfs-interaction-policy/fileReference.cjs
@@ -185,7 +185,7 @@ function parseSource(source) {
function parseDigest(digest) {
if (!isPlainObject(digest)) return { problem: 'digest must be an object' }
const extra = unknownKey(digest, DIGEST_KEYS)
- if (extra) return { problem: `digest has unknown field ${extra}` }
+ if (extra) return { problem: `digest has unknown field ${echo(extra)}` }
if (
digest.algorithm !== 'sha256' ||
typeof digest.hex !== 'string' ||
diff --git a/packages/gfs-interaction-policy/fileReference.test.cjs b/packages/gfs-interaction-policy/fileReference.test.cjs
index 35cc7c70f..ffdeb10ba 100644
--- a/packages/gfs-interaction-policy/fileReference.test.cjs
+++ b/packages/gfs-interaction-policy/fileReference.test.cjs
@@ -338,6 +338,32 @@ describe('quotePromptValue', () => {
})
assert.equal(unknownField.ok, false)
assert.equal(unknownField.message.includes(longValue), false)
+
+ const markdown = new TextEncoder().encode('# Notes\n')
+ const built = buildAttachmentFileReference({
+ attachmentId: 'att-1',
+ messageId: 'msg-1',
+ name: 'notes.md',
+ declaredMediaType: 'text/markdown',
+ byteLength: markdown.length,
+ digestHex: HEX,
+ classification: classifyBytes({
+ bytes: markdown,
+ totalByteLength: markdown.length,
+ declaredMediaType: 'text/markdown',
+ filename: 'notes.md',
+ }),
+ })
+ assert.equal(built.ok, true, built.ok ? '' : built.message)
+ const unknownDigestField = parseFileReferenceV1({
+ ...built.value,
+ digest: { ...built.value.digest, [longValue]: 1 },
+ })
+ assert.equal(unknownDigestField.ok, false)
+ // Witness: the refusal came from the digest branch, not from another check.
+ assert.match(unknownDigestField.message, /^digest has unknown field /)
+ assert.equal(unknownDigestField.message.includes(longValue), false)
+ assert.equal(unknownDigestField.message.length < 120, true)
})
it('shares the message reference-count limit', () => {
diff --git a/scripts/minikube/pre-gate-incremental.sh b/scripts/minikube/pre-gate-incremental.sh
index dcffa926b..92b6ad466 100755
--- a/scripts/minikube/pre-gate-incremental.sh
+++ b/scripts/minikube/pre-gate-incremental.sh
@@ -61,7 +61,8 @@ incremental_add_target() {
target="${selector}|${namespace}|${deployment}"
local existing
- for existing in "${INCREMENTAL_TARGETS[@]}"; do
+ # The `+` expansion keeps an empty array valid under `set -u` on bash 3.2.
+ for existing in ${INCREMENTAL_TARGETS[@]+"${INCREMENTAL_TARGETS[@]}"}; do
[[ "${existing}" == "${target}" ]] && return 0
done
INCREMENTAL_TARGETS+=("${target}")
diff --git a/scripts/tests/test-minikube-pre-gate-sync-state.sh b/scripts/tests/test-minikube-pre-gate-sync-state.sh
index 97d47607b..352d67dff 100755
--- a/scripts/tests/test-minikube-pre-gate-sync-state.sh
+++ b/scripts/tests/test-minikube-pre-gate-sync-state.sh
@@ -128,7 +128,7 @@ gfs_policy_targets="$(
# shellcheck source=/dev/null
source "$INCREMENTAL_SCRIPT"
incremental_classify_path packages/gfs-interaction-policy/fileClassifier.cjs
- printf '%s\n' "${INCREMENTAL_TARGETS[@]}"
+ printf '%s\n' ${INCREMENTAL_TARGETS[@]+"${INCREMENTAL_TARGETS[@]}"}
)"
if [[ "$gfs_policy_targets" == $'control-ui|control-plane|control-ui\nmcp-host|mcp-host|chatllm' ]]; then
pass "a gfs-interaction-policy change reshadows Control UI and mcp-host"