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.jsonindex 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.jsonindex 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.jsonindex 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.tsxindex 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 = 0const 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.tsindex 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 = falseif (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 = trueconst 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.tsindex 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.tsindex 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.jsonindex 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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>> | undefinedclient: FileReferenceGfscClientlogger: {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.tsindex 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.dataBase64const tooLarge = taskError(FileAttachmentErrorCode.TooLarge,diff --git a/mcp-host/src/agent/sourceMessageForResume.ts b/mcp-host/src/agent/sourceMessageForResume.tsindex 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 '../cimport 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 undefinedconst files = message.attachments?.filter(attachment => attachment.kind === 'file') ?? []+ const teamId = message.metadata?.teamIdreturn {- ...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.tsindex 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.tsindex 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.tsindex 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 computeddiff --git a/mcp-host/src/core/types.ts b/mcp-host/src/core/types.tsindex 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.tsindex 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.tsindex 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.tsindex 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.cjsindex 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.cjsindex 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.cjsindex 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.shindex 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 0doneINCREMENTAL_TARGETS+=("${target}")diff --git a/scripts/tests/test-minikube-pre-gate-sync-state.sh b/scripts/tests/test-minikube-pre-gate-sync-state.shindex 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/nullsource "$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' ]]; thenpass "a gfs-interaction-policy change reshadows Control UI and mcp-host"