Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
feat(chat): give kind:file attachments their own 16 MiB quota and raise the file limit to 11 MiB
Alfredo Lopezfe26567173d0
diff --git a/desktop-app/test/e2e-playwright/helpers/imageCapabilityEvidence.ts b/desktop-app/test/e2e-playwright/helpers/imageCapabilityEvidence.tsindex 50e53a8c0..e1b005734 100644--- a/desktop-app/test/e2e-playwright/helpers/imageCapabilityEvidence.ts+++ b/desktop-app/test/e2e-playwright/helpers/imageCapabilityEvidence.ts@@ -270,6 +270,11 @@ export interface FixtureProviderAttempt {* `null` on the read-request row, which carries no document yet.*/documentSha256?: string | null+ /**+ * Byte length the Host listed for the attached file (`attached_file … bytes=`).+ * Present only on the read-request row.+ */+ documentByteLength?: number}export interface FixtureEvidenceCounters {@@ -361,8 +366,29 @@ function requireAttemptRow(value: unknown, index: number, source: string): Fixtu`${source}: attempts[${index}].documentSha256 must be a sha256 hex digest or null`)}+ // Present only on the read-request row.+ if ('documentByteLength' in value) {+ const documentByteLength = value.documentByteLength+ if (+ responseKind !== FIXTURE_RESPONSE_KIND.documentReadRequested ||+ typeof documentByteLength !== 'number' ||+ !Number.isSafeInteger(documentByteLength) ||+ documentByteLength <= 0+ ) {+ throw new Error(+ `${source}: attempts[${index}].documentByteLength must be a positive integer on a ` ++ `${FIXTURE_RESPONSE_KIND.documentReadRequested} row`+ )+ }+ return { model, imageSha256, responseKind, documentSha256, documentByteLength }+ }return { model, imageSha256, responseKind, documentSha256 }}+ if ('documentByteLength' in value) {+ throw new Error(+ `${source}: attempts[${index}].documentByteLength is only valid on a document row`+ )+ }return { model, imageSha256, responseKind }}@@ -508,7 +534,8 @@ export function appendedAttempts(current.model !== row.model ||current.imageSha256 !== row.imageSha256 ||current.responseKind !== row.responseKind ||- current.documentSha256 !== row.documentSha256+ current.documentSha256 !== row.documentSha256 ||+ current.documentByteLength !== row.documentByteLength) {throw new Error(`[image-capabilities] ledger row ${index} changed between reads; the ledger must be append-only.`diff --git a/desktop-app/test/e2e-playwright/playwright.document-upload.config.ts b/desktop-app/test/e2e-playwright/playwright.document-upload.config.tsindex b37bee4e1..ef1e63b14 100644--- a/desktop-app/test/e2e-playwright/playwright.document-upload.config.ts+++ b/desktop-app/test/e2e-playwright/playwright.document-upload.config.ts@@ -43,8 +43,9 @@ const recorderRoot = process.env.QA_RECORDER_ROOTexport default defineConfig({testDir: '.',testMatch: /qa-recorder-document-upload\.spec\.ts/,- // One real Electron launch, one sign-in and one chat with two provider turns.- timeout: 300_000,+ // One real Electron launch, one sign-in and two chats (a small document and a+ // 6 MiB one), each with two provider turns.+ timeout: 480_000,expect: { timeout: 30_000 },retries: 0,workers: 1,diff --git a/desktop-app/test/e2e-playwright/qa-recorder-document-upload.spec.ts b/desktop-app/test/e2e-playwright/qa-recorder-document-upload.spec.tsindex 89836bf7f..7e129bbe2 100644--- a/desktop-app/test/e2e-playwright/qa-recorder-document-upload.spec.ts+++ b/desktop-app/test/e2e-playwright/qa-recorder-document-upload.spec.ts@@ -43,6 +43,13 @@ import {* answer on screen can only be produced if the exact bytes attached here crossed* the composer, IPC, the Host admission, the read tool and the provider wire.*+ * A second chat sends a 6 MiB document. Its base64 exceeds the 6 MiB text share,+ * so it reaches the Host only through the credited `kind:'file'` quota in+ * rpc-proxy and mcp-host. Its pages exceed the Host spillover threshold, so the+ * fixture (which refuses a spillover summary) answers only when the read tool's+ * page travels inline. The answer carries the digest of the first page, and the+ * ledger carries the byte length the Host verified for the whole file.+ ** Only the external provider peer is simulated. The run is selected by the* fixture lane's own run id and never reaches a real provider.*/@@ -155,8 +162,26 @@ function sentMessageAttachments(page: Page) {return page.getByLabel('Message attachments')}-/** Per-file ceiling the composer enforces; it mirrors the Host default (3 MiB). */-const COMPOSER_FILE_LIMIT_BYTES = 3 * 1024 * 1024+/**+ * Per-file ceiling the composer enforces; it mirrors the Host default+ * `CLERUM_ATTACHMENT_FILE_MAX_BYTES` (11 MiB).+ */+const COMPOSER_FILE_LIMIT_BYTES = 11 * 1024 * 1024++/**+ * A document whose base64 (8 MiB) exceeds the 6 MiB text share. It reaches the+ * Host only because rpc-proxy and mcp-host credit `kind:'file'` base64 to its+ * own quota; with the old limits rpc-proxy answers 413 and the Host refuses it.+ */+const LARGE_DOCUMENT_BYTES = 6 * 1024 * 1024++/**+ * Default page `clerum__attachment_read` returns+ * (`CLERUM_ATTACHMENT_TEXT_READ_MAX_BYTES`). The fixture digests the text of+ * the first page it receives, so a larger document is identified by the digest+ * of its first page.+ */+const ATTACHMENT_READ_PAGE_BYTES = 65_536/** Start a blank chat and prove the thread is empty before anything is sent. */async function startBlankChat(page: Page) {@@ -254,6 +279,62 @@ function documentAnswerRegex(documentSha: string): RegExp {return new RegExp(`${prefix}${documentSha.slice(0, FIXTURE_DOCUMENT_ANSWER_DIGEST_CHARS)}`, 'i')}+/**+ * Sends the composer's single ready document and proves the round trip: the+ * sent bubble lists the file, the answer carries the digest of the text the+ * read tool returned, and the fixture ledger shows one read request carrying+ * the byte length the Host verified and one answer carrying that digest.+ */+async function sendDocumentAndVerifyAnswer(+ page: Page,+ env: ReturnType<typeof requireImageCapabilitiesFixtureEnv>,+ assertBinding: () => Promise<void>,+ document: { fileName: string; buffer: Buffer },+ readTextSha: string+) {+ const before = readImageCapabilityEvidence(env)+ await assertBinding()+ await sendButton(page).click()+ await expect(fileChips(page)).toHaveCount(0, { timeout: 30_000 })++ await expect(page.getByTestId('message-list')).toBeVisible({ timeout: 20_000 })+ await expect(page.locator('[data-chat-message-id]')).toHaveCount(2, { timeout: 120_000 })+ // The sent bubble shows the attachment the user picked, not only the model's answer.+ await expect(sentMessageAttachments(page)).toHaveCount(1, { timeout: 20_000 })+ await expect(sentMessageAttachments(page)).toContainText(document.fileName)+ const response = page.getByTestId('agent-response').locator('.message-block.markdown-content')+ await expect(response).toHaveCount(1, { timeout: 120_000 })+ await expect(response).toContainText(documentAnswerRegex(readTextSha), { timeout: 120_000 })+ await observeCompletedTask(page, env.hostRef, documentAnswerRegex(readTextSha))++ const after = readImageCapabilityEvidence(env)+ const appended = appendedAttempts(before, after)+ const readRows = appended.filter(+ row => row.responseKind === FIXTURE_RESPONSE_KIND.documentReadRequested+ )+ const answerRows = appended.filter(+ row => row.responseKind === FIXTURE_RESPONSE_KIND.documentAnswer+ )++ // Turn 1: the model asked for the read tool. The prompt alone produced no answer.+ expect(readRows).toHaveLength(1)+ expect(readRows[0]?.model).toBe(IMAGE_CAPABILITY_FIXTURE_MODELS.supported)+ expect(readRows[0]?.documentSha256).toBeNull()+ // The Host announced the whole file: the byte length it verified on admission.+ expect(readRows[0]?.documentByteLength).toBe(document.buffer.length)+ // Turn 2: the tool result reached the wire carrying exactly the attached bytes.+ expect(answerRows).toHaveLength(1)+ expect(answerRows[0]?.model).toBe(IMAGE_CAPABILITY_FIXTURE_MODELS.supported)+ expect(answerRows[0]?.documentSha256).toBe(readTextSha)++ // A document is never an image: no pixels moved, and the fixture refused nothing.+ expect(appended.filter(row => row.imageSha256 !== null)).toHaveLength(0)+ expect(after.counters.imageAttempts - before.counters.imageAttempts).toBe(0)+ expect(after.counters.documentReadRequests - before.counters.documentReadRequests).toBe(1)+ expect(after.counters.documentAnswers - before.counters.documentAnswers).toBe(1)+ expect(after.counters.documentFailures - before.counters.documentFailures).toBe(0)+}+test('document-upload fixture: an attached text file reaches the model through the read tool', async ({}, testInfo) => {test.skip(MODE !== 'fixture',@@ -279,8 +360,22 @@ test('document-upload fixture: an attached text file reaches the model through tbuffer: Buffer.from(`document-upload ${randomBytes(6).toString('hex')}\nsecond line\n`, 'utf8'),}const documentSha = sha256Hex(document.buffer)++ // Run-unique ASCII (hex of random bytes): its first page differs from every+ // other run's, and in ASCII the byte cut and the text cut of a page coincide.+ const largeDocument = {+ fileName: `large-notes-${randomBytes(3).toString('hex')}.txt`,+ mimeType: 'text/plain',+ buffer: Buffer.from(randomBytes(LARGE_DOCUMENT_BYTES / 2).toString('hex'), 'ascii'),+ }+ expect(largeDocument.buffer.length).toBe(LARGE_DOCUMENT_BYTES)+ const largeDocumentPageSha = sha256Hex(+ largeDocument.buffer.subarray(0, ATTACHMENT_READ_PAGE_BYTES)+ )+fs.mkdirSync(testInfo.outputPath(), { recursive: true })fs.writeFileSync(testInfo.outputPath(document.fileName), document.buffer)+ fs.writeFileSync(testInfo.outputPath(largeDocument.fileName), largeDocument.buffer)let app: ElectronApplication | undefinedlet recordedPage: Page | undefined@@ -315,7 +410,7 @@ test('document-upload fixture: an attached text file reaches the model through t// Liveness witness: the refusal the composer had to produce is on screen.const refusal = page.getByRole('alert').filter({ hasText: oversized.fileName })await expect(refusal).toHaveCount(1, { timeout: 15_000 })- await expect(refusal).toContainText(/a file can be at most 3\.0 MiB/)+ await expect(refusal).toContainText(/a file can be at most 11\.0 MiB/)await expect(fileChips(page)).toHaveCount(0)})@@ -344,45 +439,47 @@ test('document-upload fixture: an attached text file reaches the model through t})await test.step('the answer carries the digest of the delivered text and the ledger shows both provider turns', async () => {- const before = readImageCapabilityEvidence(env)- await assertBinding()- await sendButton(page).click()- await expect(fileChips(page)).toHaveCount(0, { timeout: 30_000 })-- await expect(page.getByTestId('message-list')).toBeVisible({ timeout: 20_000 })- await expect(page.locator('[data-chat-message-id]')).toHaveCount(2, { timeout: 120_000 })- // The sent bubble shows the attachment the user picked, not only the model's answer.- await expect(sentMessageAttachments(page)).toHaveCount(1, { timeout: 20_000 })- await expect(sentMessageAttachments(page)).toContainText(document.fileName)- const response = page.getByTestId('agent-response').locator('.message-block.markdown-content')- await expect(response).toHaveCount(1, { timeout: 120_000 })- await expect(response).toContainText(documentAnswerRegex(documentSha), { timeout: 120_000 })- await observeCompletedTask(page, env.hostRef, documentAnswerRegex(documentSha))-- const after = readImageCapabilityEvidence(env)- const appended = appendedAttempts(before, after)- const readRows = appended.filter(- row => row.responseKind === FIXTURE_RESPONSE_KIND.documentReadRequested- )- const answerRows = appended.filter(- row => row.responseKind === FIXTURE_RESPONSE_KIND.documentAnswer- )+ await sendDocumentAndVerifyAnswer(page, env, assertBinding, document, documentSha)+ })++ await test.step('a 6 MiB document above the old text share is admitted as a ready chip', async () => {+ await startBlankChat(page)+ await selectSupportedModel(page, IMAGE_CAPABILITY_FIXTURE_MODELS.supported)+ await attachDocument(page, largeDocument)+ const chip = fileChips(page).filter({ hasText: largeDocument.fileName })+ await expect(chip).toHaveCount(1, { timeout: 30_000 })+ await expect(chip).toHaveAttribute('data-file-status', 'ready', { timeout: 60_000 })+ // The chip reports the whole file the composer read, not a truncated copy.+ await expect(chip).toContainText('6.0 MiB')+ })- // Turn 1: the model asked for the read tool. The prompt alone produced no answer.- expect(readRows).toHaveLength(1)- expect(readRows[0]?.model).toBe(IMAGE_CAPABILITY_FIXTURE_MODELS.supported)- expect(readRows[0]?.documentSha256).toBeNull()- // Turn 2: the tool result reached the wire carrying exactly the attached bytes.- expect(answerRows).toHaveLength(1)- expect(answerRows[0]?.model).toBe(IMAGE_CAPABILITY_FIXTURE_MODELS.supported)- expect(answerRows[0]?.documentSha256).toBe(documentSha)-- // A document is never an image: no pixels moved, and the fixture refused nothing.- expect(appended.filter(row => row.imageSha256 !== null)).toHaveLength(0)- expect(after.counters.imageAttempts - before.counters.imageAttempts).toBe(0)- expect(after.counters.documentReadRequests - before.counters.documentReadRequests).toBe(1)- expect(after.counters.documentAnswers - before.counters.documentAnswers).toBe(1)- expect(after.counters.documentFailures - before.counters.documentFailures).toBe(0)+ await test.step('a file that would overflow the 16 MiB file quota is refused and the ready chip stays', async () => {+ const overQuota = {+ fileName: `over-quota-${randomBytes(3).toString('hex')}.txt`,+ mimeType: 'text/plain',+ buffer: Buffer.alloc(COMPOSER_FILE_LIMIT_BYTES, 0x61),+ }+ await attachDocument(page, overQuota)+ // Liveness witness: the quota refusal the composer had to produce is on screen.+ const refusal = page.getByRole('alert').filter({ hasText: overQuota.fileName })+ await expect(refusal).toHaveCount(1, { timeout: 15_000 })+ await expect(refusal).toContainText(/files in a message can take at most 16\.0 MiB/)+ await expect(fileChips(page)).toHaveCount(1)+ const chip = fileChips(page).filter({ hasText: largeDocument.fileName })+ await expect(chip).toHaveAttribute('data-file-status', 'ready')++ await composer(page).fill(DOCUMENT_PROMPT)+ await expect(sendButton(page)).toBeEnabled({ timeout: 20_000 })+ })++ await test.step('the 6 MiB document is sent, read inline and answered with the digest of its first page', async () => {+ await sendDocumentAndVerifyAnswer(+ page,+ env,+ assertBinding,+ largeDocument,+ largeDocumentPageSha+ )})await screenshotAndLog(page, testInfo, 'desktop-document-upload-fixture')diff --git a/desktop-app/ui/src/constants/attachments.ts b/desktop-app/ui/src/constants/attachments.tsindex 2990831a4..0f1e39c62 100644--- a/desktop-app/ui/src/constants/attachments.ts+++ b/desktop-app/ui/src/constants/attachments.ts@@ -6,14 +6,23 @@ export const COMPOSER_MAX_ATTACHMENTS = 20/*** Per-file ceiling for a document sent as `kind:'file'`. Must match the- * `CLERUM_ATTACHMENT_FILE_MAX_BYTES` default of mcp-host (`attachmentFileMaxBytes`).+ * `CLERUM_ATTACHMENT_FILE_MAX_BYTES` default of mcp-host (`attachmentFileMaxBytes`)+ * and `MAX_FILE_DECODED_BYTES` in `rpc-proxy/src/middleware/chatJsonBody.ts` and+ * in `mcp-host/src/server.ts`.*/-export const COMPOSER_MAX_FILE_BYTES = 3 * 1024 * 1024+export const COMPOSER_MAX_FILE_BYTES = 11 * 1024 * 1024/**- * Share of one chat request body that is not credited to the image quota: the- * base64 of every `kind:'file'`, the text and the JSON envelope. Must match- * `MAX_NON_IMAGE_BODY_BYTES` in `rpc-proxy/src/middleware/chatJsonBody.ts` and- * in `mcp-host/src/server.ts`.+ * Combined base64 size of the files in one message. Files have their own quota+ * in rpc-proxy and mcp-host, like images. Must match+ * `MAX_FILE_BASE64_BYTES_TOTAL` in `rpc-proxy/src/middleware/chatJsonBody.ts`+ * and in `mcp-host/src/server.ts`.+ */+export const COMPOSER_MAX_TOTAL_FILE_BASE64_BYTES = 16 * 1024 * 1024+/**+ * Share of one chat request body that is credited to neither the image quota+ * nor the file quota: the text, the JSON envelope and every field of a+ * `kind:'file'` entry except its base64. Must match `MAX_NON_IMAGE_BODY_BYTES`+ * in `rpc-proxy/src/middleware/chatJsonBody.ts` and in `mcp-host/src/server.ts`.*/export const COMPOSER_MAX_NON_IMAGE_BODY_BYTES = 6 * 1024 * 1024/**diff --git a/desktop-app/ui/src/hooks/domain/__tests__/useAgentChatController.test.tsx b/desktop-app/ui/src/hooks/domain/__tests__/useAgentChatController.test.tsxindex 9e82e9687..07941abe4 100644--- a/desktop-app/ui/src/hooks/domain/__tests__/useAgentChatController.test.tsx+++ b/desktop-app/ui/src/hooks/domain/__tests__/useAgentChatController.test.tsx@@ -13,6 +13,11 @@import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'import { makeTaskKey } from '@contexts/AgentTaskTrackerContext/types'import { act, waitFor } from '@testing-library/react'+import { classifyBytes } from '@clerum/gfs-interaction-policy'+import { base64Length } from '@lib/composerFileAdmission'+import { loadHostModels, resetHostModelSelectionStore } from '@lib/hostModelSelectionStore'+import type { HostModelsResult } from '../../../../../src/types'+import type { ComposerImageAttachment, ReadyComposerFileAttachment } from '../../../uiTypes'import { renderController } from './__fixtures__/controllerHarness'import { type MockClerum, installMockClerum, uninstallMockClerum } from './__fixtures__/mockClerum'@@ -1761,3 +1766,186 @@ describe('interrupted generated-file contract', () => {])})})++/**+ * #678 — the send-time blockers for documents. Files enter through the public+ * restore action (the path a retried send uses), which skips the picker's+ * admission, so each blocker is reached exactly as the controller sees it at+ * send time. Every refusal is paired, in the same test, with a twin one step+ * inside the limit that reaches the Host once.+ */+describe('sendAgentMessage — per-message limits for documents (#678)', () => {+ const MIB = 1024 * 1024+ const TEXT_SHARE_BLOCKER =+ 'The message text and file details take more than 6.0 MiB once encoded. Shorten the message or remove a file.'+ const FILE_QUOTA_BLOCKER =+ 'The attached files take more than 16.0 MiB once encoded. Remove a file.'+ const REQUEST_BODY_BLOCKER =+ 'The attachments and text take more than 24.0 MiB once encoded. Remove an attachment or shorten the message.'+ const COUNT_BLOCKER = 'A message can carry at most 20 attachments.'++ const catalog: HostModelsResult = {+ provider: 'zai',+ hostDefault: 'glm-5.3-flash',+ sessionModel: null,+ degraded: false,+ modelSelectionRevision: 0,+ models: [{ name: 'glm-5.3-flash', imageInput: { state: 'supported', reason: 'supported' } }],+ }+ const modelTransport = {+ getHostModels: vi.fn(async () => catalog),+ setHostModel: vi.fn(),+ }++ afterEach(() => {+ resetHostModelSelectionStore()+ })++ /** A read and hashed text document of `sizeBytes`, as `readComposerFile` returns it. */+ function readyTextFile(+ id: string,+ filename: string,+ sizeBytes: number+ ): ReadyComposerFileAttachment {+ return {+ id,+ type: 'file',+ filename,+ sizeBytes,+ declaredMediaType: 'text/plain',+ status: 'ready',+ classification: classifyBytes({+ // Built with this environment's Uint8Array, as readComposerFile does:+ // TextEncoder and Buffer return one from another realm under jsdom.+ bytes: new Uint8Array(Buffer.from('plain text')),+ totalByteLength: sizeBytes,+ declaredMediaType: 'text/plain',+ filename,+ }),+ dataBase64: 'Y'.repeat(base64Length(sizeBytes)),+ digestHex: 'ab'.repeat(32),+ }+ }++ async function mountedWithFiles(files: ReadyComposerFileAttachment[]) {+ clerum.rpc.invokeHostMessage.mockResolvedValue({ response: 'done' })+ const rendered = renderController()+ await settleMount()+ act(() => rendered.result.current.handleRestoreComposerFiles(files))+ return rendered+ }++ function sentAttachmentIds(): unknown[] {+ const request = clerum.rpc.invokeHostMessage.mock.calls[0]?.[1] as {+ attachments?: Array<{ id: unknown }>+ }+ expect(request).toBeDefined()+ return (request.attachments ?? []).map(attachment => attachment.id)+ }++ function expectBlocked(rendered: ReturnType<typeof renderController>, blocker: string) {+ expect(rendered.result.current.agentError).toBe(blocker)+ expect(rendered.spies.pushToast).toHaveBeenCalledWith(blocker, 'error')+ expect(clerum.chat.create).not.toHaveBeenCalled()+ expect(clerum.rpc.invokeHostMessage).not.toHaveBeenCalled()+ }++ it('refuses text that overflows the 6 MiB share beside an 11 MiB file, and sends one byte less', async () => {+ const big = readyTextFile('file-big', 'big.txt', 11 * MIB)+ const rendered = await mountedWithFiles([big])+ // Envelope (4096) + text + the file's JSON name and fixed fields; the file's+ // base64 is credited to the file quota.+ const fullShareText = 6 * MIB - 4096 - JSON.stringify('big.txt').length - 640++ await act(async () => {+ await rendered.result.current.handleSendAgentMessage('x'.repeat(fullShareText + 1))+ })+ expectBlocked(rendered, TEXT_SHARE_BLOCKER)+ expect(rendered.result.current.composerFileAttachments).toHaveLength(1)++ await act(async () => {+ await rendered.result.current.handleSendAgentMessage('x'.repeat(fullShareText))+ })+ expect(clerum.rpc.invokeHostMessage).toHaveBeenCalledTimes(1)+ expect(sentAttachmentIds()).toEqual(['file-big'])+ })++ it('refuses files one byte past the 16 MiB quota, and sends the pair that fills it exactly', async () => {+ const big = readyTextFile('file-big', 'big.txt', 11 * MIB)+ const rendered = await mountedWithFiles([+ big,+ readyTextFile('file-over', 'tail.txt', 1_048_576),+ ])++ await act(async () => {+ await rendered.result.current.handleSendAgentMessage('read both')+ })+ expectBlocked(rendered, FILE_QUOTA_BLOCKER)++ act(() =>+ rendered.result.current.handleRestoreComposerFiles([+ big,+ readyTextFile('file-fits', 'tail.txt', 1_048_575),+ ])+ )+ await act(async () => {+ await rendered.result.current.handleSendAgentMessage('read both')+ })+ expect(clerum.rpc.invokeHostMessage).toHaveBeenCalledTimes(1)+ expect(sentAttachmentIds()).toEqual(['file-big', 'file-fits'])+ })++ it('refuses images and files that together pass the 24 MiB body, and sends without one file', async () => {+ const big = readyTextFile('file-big', 'big.txt', 11 * MIB)+ const rendered = await mountedWithFiles([+ big,+ readyTextFile('file-tail', 'tail.txt', 1_048_575),+ ])+ await act(async () => {+ await loadHostModels(modelTransport, 'agent-x', null)+ })+ const image: ComposerImageAttachment = {+ id: 'image-8mib',+ name: 'scan.png',+ mimeType: 'image/png',+ dataBase64: 'A'.repeat(8 * MIB),+ sizeBytes: 6 * MIB,+ previewDataUrl: 'data:image/png;base64,AAAA',+ }+ act(() => rendered.result.current.handleAddComposerImageAttachments([image]))+ // Precondition: the files sit exactly on their quota and the text is short,+ // so only the whole-body limit can refuse this send.+ expect(base64Length(11 * MIB) + base64Length(1_048_575)).toBe(16 * MIB)++ await act(async () => {+ await rendered.result.current.handleSendAgentMessage('describe')+ })+ expectBlocked(rendered, REQUEST_BODY_BLOCKER)++ act(() => rendered.result.current.handleRestoreComposerFiles([big]))+ await act(async () => {+ await rendered.result.current.handleSendAgentMessage('describe')+ })+ expect(clerum.rpc.invokeHostMessage).toHaveBeenCalledTimes(1)+ expect(sentAttachmentIds()).toEqual(expect.arrayContaining(['file-big', 'image-8mib']))+ })++ it('refuses a twenty-first attachment and sends twenty', async () => {+ const files = Array.from({ length: 21 }, (_, index) =>+ readyTextFile(`file-${index}`, `part-${index}.txt`, 10)+ )+ const rendered = await mountedWithFiles(files)++ await act(async () => {+ await rendered.result.current.handleSendAgentMessage('read all')+ })+ expectBlocked(rendered, COUNT_BLOCKER)++ act(() => rendered.result.current.handleRestoreComposerFiles(files.slice(0, 20)))+ await act(async () => {+ await rendered.result.current.handleSendAgentMessage('read all')+ })+ expect(clerum.rpc.invokeHostMessage).toHaveBeenCalledTimes(1)+ expect(sentAttachmentIds()).toHaveLength(20)+ })+})diff --git a/desktop-app/ui/src/hooks/domain/__tests__/useComposerAttachments.files.test.tsx b/desktop-app/ui/src/hooks/domain/__tests__/useComposerAttachments.files.test.tsxindex c210adb16..ab9400910 100644--- a/desktop-app/ui/src/hooks/domain/__tests__/useComposerAttachments.files.test.tsx+++ b/desktop-app/ui/src/hooks/domain/__tests__/useComposerAttachments.files.test.tsx@@ -118,7 +118,9 @@ describe('useComposerAttachments — documents (#678)', () => {const [failed] = result.current.composerFileAttachmentsexpect(failed?.status).toBe('failed')- expect(failed?.status === 'failed' && failed.error).toMatch(/^huge\.bin is .* at most 3\.0 MiB/)+ expect(failed?.status === 'failed' && failed.error).toMatch(+ /^huge\.bin is .* at most 11\.0 MiB/+ )// Witness for "never reads it": the chip exists, and the reader was not called.expect(read).not.toHaveBeenCalled()})diff --git a/desktop-app/ui/src/hooks/domain/useAgentChatController.ts b/desktop-app/ui/src/hooks/domain/useAgentChatController.tsindex 264d75b80..728047aa5 100644--- a/desktop-app/ui/src/hooks/domain/useAgentChatController.ts+++ b/desktop-app/ui/src/hooks/domain/useAgentChatController.ts@@ -6,7 +6,12 @@ import {parseTaskKey,useAgentTaskTracker,} from '@contexts/AgentTaskTrackerContext'-import { COMPOSER_MAX_ATTACHMENTS, COMPOSER_MAX_NON_IMAGE_BODY_BYTES } from '@constants/attachments'+import {+ COMPOSER_MAX_ATTACHMENTS,+ COMPOSER_MAX_NON_IMAGE_BODY_BYTES,+ COMPOSER_MAX_REQUEST_BODY_BYTES,+ COMPOSER_MAX_TOTAL_FILE_BASE64_BYTES,+} from '@constants/attachments'import {buildChatMessageAttachments,buildResponseFileAttachments,@@ -17,7 +22,12 @@ import {getComposerDraftRevision,setComposerDraft,} from '@lib/composerDraftStore'-import { composerNonImageBodyBytes, formatFileSize } from '@lib/composerFileAdmission'+import {+ composerFileBase64Bytes,+ composerNonImageBodyBytes,+ composerRequestBodyBytes,+ formatFileSize,+} from '@lib/composerFileAdmission'import { buildComposerFileReferences } from '@lib/composerFileReferences'import { buildComposerRequestContent } from '@lib/composerReferencesPrompt'import {@@ -2621,17 +2631,33 @@ export function useAgentChatController({effectiveReferences)if (effectiveFiles.length > 0) {- const attachmentCount = effectiveAttachments.length + effectiveFiles.length- const nonImageBodyBytes = composerNonImageBodyBytes({- files: effectiveFiles,- textBytes: new TextEncoder().encode(effectiveContentForRequest).length,- })- const blocker =- attachmentCount > COMPOSER_MAX_ATTACHMENTS- ? `A message can carry at most ${COMPOSER_MAX_ATTACHMENTS} attachments.`- : nonImageBodyBytes > COMPOSER_MAX_NON_IMAGE_BODY_BYTES- ? `The attached files and text take more than ${formatFileSize(COMPOSER_MAX_NON_IMAGE_BODY_BYTES)} once encoded. Remove a file or shorten the message.`- : null+ // The limits rpc-proxy and mcp-host enforce, most specific first: the+ // count, the file quota, the share left for text and file details, then+ // the whole body (images included), so the reason names what to remove.+ const textBytes = new TextEncoder().encode(effectiveContentForRequest).length+ let blocker: string | null = null+ if (effectiveAttachments.length + effectiveFiles.length > COMPOSER_MAX_ATTACHMENTS) {+ blocker = `A message can carry at most ${COMPOSER_MAX_ATTACHMENTS} attachments.`+ } else if (composerFileBase64Bytes(effectiveFiles) > COMPOSER_MAX_TOTAL_FILE_BASE64_BYTES) {+ blocker = `The attached files take more than ${formatFileSize(COMPOSER_MAX_TOTAL_FILE_BASE64_BYTES)} once encoded. Remove a file.`+ } else if (+ composerNonImageBodyBytes({ files: effectiveFiles, textBytes }) >+ COMPOSER_MAX_NON_IMAGE_BODY_BYTES+ ) {+ blocker = `The message text and file details take more than ${formatFileSize(COMPOSER_MAX_NON_IMAGE_BODY_BYTES)} once encoded. Shorten the message or remove a file.`+ } else if (+ composerRequestBodyBytes({+ files: effectiveFiles,+ textBytes,+ imageBase64Bytes: effectiveAttachments.reduce(+ (total, image) => total + image.dataBase64.length,+ 0+ ),+ imageCount: effectiveAttachments.length,+ }) > COMPOSER_MAX_REQUEST_BODY_BYTES+ ) {+ blocker = `The attachments and text take more than ${formatFileSize(COMPOSER_MAX_REQUEST_BODY_BYTES)} once encoded. Remove an attachment or shorten the message.`+ }if (blocker) {setAgentError(blocker)pushToast(blocker, 'error')diff --git a/desktop-app/ui/src/lib/__tests__/composerFileAdmission.test.ts b/desktop-app/ui/src/lib/__tests__/composerFileAdmission.test.tsindex 07f93cd61..61798ba5b 100644--- a/desktop-app/ui/src/lib/__tests__/composerFileAdmission.test.ts+++ b/desktop-app/ui/src/lib/__tests__/composerFileAdmission.test.ts@@ -5,13 +5,16 @@ import {COMPOSER_MAX_ATTACHMENTS,COMPOSER_MAX_FILE_BYTES,COMPOSER_MAX_NON_IMAGE_BODY_BYTES,+ COMPOSER_MAX_TOTAL_FILE_BASE64_BYTES,COMPOSER_REQUEST_ENVELOPE_BYTES,} from '@constants/attachments'import {base64Length,composerFileAdmissionError,- composerFileEntryBytes,+ composerFileBase64Bytes,+ composerFileDetailBytes,composerNonImageBodyBytes,+ composerRequestBodyBytes,fileNameProblem,readComposerFile,} from '../composerFileAdmission'@@ -114,7 +117,7 @@ describe('composerFileAdmissionError (#678)', () => {{ name: 'a.bin', size: COMPOSER_MAX_FILE_BYTES + 1 },EMPTY_CONTEXT)- ).toContain('a file can be at most 3.0 MiB')+ ).toContain('a file can be at most 11.0 MiB')})it('rejects the 21st attachment and admits the 20th', () => {@@ -132,10 +135,10 @@ describe('composerFileAdmissionError (#678)', () => {).toContain(`at most ${COMPOSER_MAX_ATTACHMENTS} attachments`)})- it('rejects a file whose base64 no longer fits the non-image share of the body', () => {+ it('rejects a second 11 MiB file with the file quota message (#678)', () => {const first = { filename: 'first.bin', sizeBytes: COMPOSER_MAX_FILE_BYTES }// Liveness witness: the first file alone is admitted, so the rejection below- // comes from the budget check and not from a per-file or count limit.+ // comes from the file quota and not from a per-file or count limit.expect(composerFileAdmissionError({ name: 'first.bin', size: COMPOSER_MAX_FILE_BYTES },@@ -147,10 +150,26 @@ describe('composerFileAdmissionError (#678)', () => {{ name: 'second.bin', size: COMPOSER_MAX_FILE_BYTES },{ attachedCount: 1, files: [first], textBytes: 0 })- ).toContain('does not fit')+ ).toBe(+ 'second.bin does not fit: the files in a message can take at most 16.0 MiB once encoded.'+ )+ })++ it('fills the 16 MiB file quota exactly and refuses one byte more (#678)', () => {+ const first = { filename: 'first.bin', sizeBytes: COMPOSER_MAX_FILE_BYTES }+ const context = { attachedCount: 1, files: [first], textBytes: 0 }+ // 11 MiB encodes to 15_379_116 chars; 1_048_575 B adds 1_398_100 and+ // lands on 16_777_216; 1_048_576 B adds 1_398_104.+ expect(base64Length(COMPOSER_MAX_FILE_BYTES) + base64Length(1_048_575)).toBe(+ COMPOSER_MAX_TOTAL_FILE_BASE64_BYTES+ )+ expect(composerFileAdmissionError({ name: 'fits.bin', size: 1_048_575 }, context)).toBeNull()+ expect(composerFileAdmissionError({ name: 'over.bin', size: 1_048_576 }, context)).toContain(+ 'the files in a message can take at most 16.0 MiB'+ )})- it('counts the message text against the same share', () => {+ it('counts the message text against the 6 MiB share, not against the file quota', () => {const file = { name: 'a.bin', size: 1024 }expect(composerFileAdmissionError(file, EMPTY_CONTEXT)).toBeNull()expect(@@ -158,7 +177,26 @@ describe('composerFileAdmissionError (#678)', () => {...EMPTY_CONTEXT,textBytes: COMPOSER_MAX_NON_IMAGE_BODY_BYTES,})- ).toContain('does not fit')+ ).toBe(+ 'a.bin does not fit: the text and file details can take at most 6.0 MiB per message once encoded.'+ )+ })++ it('admits an 11 MiB file beside text that fills the 6 MiB share exactly (#678)', () => {+ const file = { name: 'big.bin', size: COMPOSER_MAX_FILE_BYTES }+ // The share holds the envelope, the text and the file's JSON name plus+ // fixed fields; the file's base64 is credited to the file quota.+ const fullShareText =+ COMPOSER_MAX_NON_IMAGE_BODY_BYTES -+ COMPOSER_REQUEST_ENVELOPE_BYTES -+ JSON.stringify('big.bin').length -+ COMPOSER_FILE_ENTRY_METADATA_BYTES+ expect(+ composerFileAdmissionError(file, { ...EMPTY_CONTEXT, textBytes: fullShareText })+ ).toBeNull()+ expect(+ composerFileAdmissionError(file, { ...EMPTY_CONTEXT, textBytes: fullShareText + 1 })+ ).toContain('the text and file details can take at most 6.0 MiB')})it.each([@@ -179,24 +217,46 @@ describe('composerFileAdmissionError (#678)', () => {})})-describe('composerNonImageBodyBytes (#678)', () => {- it('adds the envelope, the text and the base64 plus metadata of each file', () => {+describe('composer request body accounting (#678)', () => {+ it('charges the envelope, the text and the file details, but not the file base64, to the share', () => {const file = { filename: 'a.pdf', sizeBytes: 1000 }expect(composerNonImageBodyBytes({ files: [file], textBytes: 50 })).toBe(COMPOSER_REQUEST_ENVELOPE_BYTES +50 +- base64Length(1000) +JSON.stringify('a.pdf').length +COMPOSER_FILE_ENTRY_METADATA_BYTES)- expect(composerFileEntryBytes(file)).toBe(- base64Length(1000) + JSON.stringify('a.pdf').length + COMPOSER_FILE_ENTRY_METADATA_BYTES+ expect(composerFileDetailBytes(file)).toBe(+ JSON.stringify('a.pdf').length + COMPOSER_FILE_ENTRY_METADATA_BYTES+ )+ })++ it('charges the base64 of every file to the file quota', () => {+ expect(composerFileBase64Bytes([{ sizeBytes: 1000 }, { sizeBytes: 1 }, { sizeBytes: 0 }])).toBe(+ base64Length(1000) + 4+ )+ })++ it('adds the share, the file base64 and the images to size the whole body', () => {+ const files = [{ filename: 'a.pdf', sizeBytes: 1000 }]+ expect(+ composerRequestBodyBytes({+ files,+ textBytes: 50,+ imageBase64Bytes: 8_000,+ imageCount: 2,+ })+ ).toBe(+ composerNonImageBodyBytes({ files, textBytes: 50 }) ++ base64Length(1000) ++ 8_000 ++ 2 * COMPOSER_FILE_ENTRY_METADATA_BYTES)})it('measures a multi-byte name in UTF-8 bytes', () => {- const ascii = composerFileEntryBytes({ filename: 'aaaa.txt', sizeBytes: 0 })- const accented = composerFileEntryBytes({ filename: 'ññññ.txt', sizeBytes: 0 })+ const ascii = composerFileDetailBytes({ filename: 'aaaa.txt' })+ const accented = composerFileDetailBytes({ filename: 'ññññ.txt' })expect(accented - ascii).toBe(4)})})diff --git a/desktop-app/ui/src/lib/composerFileAdmission.ts b/desktop-app/ui/src/lib/composerFileAdmission.tsindex 30a897e05..02ba5dc1b 100644--- a/desktop-app/ui/src/lib/composerFileAdmission.ts+++ b/desktop-app/ui/src/lib/composerFileAdmission.ts@@ -4,6 +4,7 @@ import {COMPOSER_MAX_ATTACHMENTS,COMPOSER_MAX_FILE_BYTES,COMPOSER_MAX_NON_IMAGE_BODY_BYTES,+ COMPOSER_MAX_TOTAL_FILE_BASE64_BYTES,COMPOSER_REQUEST_ENVELOPE_BYTES,} from '@constants/attachments'import type { ComposerFileAttachment } from '../uiTypes'@@ -18,7 +19,10 @@ const textEncoder = new TextEncoder()export type ComposerFileAdmissionContext = {/** Images and files already attached to the message. */attachedCount: number- /** Files already attached; their base64 counts against the non-image share. */+ /**+ * Files already attached. Their base64 counts against the file quota; their+ * name and fixed fields count against the non-image share.+ */files: ReadonlyArray<Pick<ComposerFileAttachment, 'filename' | 'sizeBytes'>>/** UTF-8 length of the message text as it will be sent. */textBytes: number@@ -35,27 +39,54 @@ export function base64Length(sizeBytes: number): number {return Math.ceil(sizeBytes / 3) * 4}-/** Bytes one `kind:'file'` entry adds to the JSON request body. */-export function composerFileEntryBytes(file: { filename: string; sizeBytes: number }): number {+/**+ * Bytes one `kind:'file'` entry adds to the JSON request body besides its+ * base64: the file name and the fixed fields. rpc-proxy and mcp-host charge+ * these to the non-image share; only the base64 is credited to the file quota.+ */+export function composerFileDetailBytes(file: { filename: string }): number {return (- base64Length(file.sizeBytes) +- textEncoder.encode(JSON.stringify(file.filename)).length +- COMPOSER_FILE_ENTRY_METADATA_BYTES+ textEncoder.encode(JSON.stringify(file.filename)).length + COMPOSER_FILE_ENTRY_METADATA_BYTES)}+/** Bytes of base64 the file quota is charged for these files. */+export function composerFileBase64Bytes(files: ReadonlyArray<{ sizeBytes: number }>): number {+ return files.reduce((total, file) => total + base64Length(file.sizeBytes), 0)+}+/**- * Bytes of one request body that rpc-proxy and mcp-host do not credit to the- * image quota: the JSON envelope, the message text and every `kind:'file'`.+ * Bytes of one request body that rpc-proxy and mcp-host credit to neither the+ * image quota nor the file quota: the JSON envelope, the message text and the+ * non-base64 fields of every `kind:'file'`.*/export function composerNonImageBodyBytes(input: {- files: ReadonlyArray<{ filename: string; sizeBytes: number }>+ files: ReadonlyArray<{ filename: string }>textBytes: number}): number {return (COMPOSER_REQUEST_ENVELOPE_BYTES +input.textBytes +- input.files.reduce((total, file) => total + composerFileEntryBytes(file), 0)+ input.files.reduce((total, file) => total + composerFileDetailBytes(file), 0)+ )+}++/**+ * Bytes of the whole request body: the non-image share plus the base64 of the+ * files and of the images. An image entry is counted with the same fixed-field+ * allowance as a file entry, which is an upper bound.+ */+export function composerRequestBodyBytes(input: {+ files: ReadonlyArray<{ filename: string; sizeBytes: number }>+ textBytes: number+ imageBase64Bytes: number+ imageCount: number+}): number {+ return (+ composerNonImageBodyBytes(input) ++ composerFileBase64Bytes(input.files) ++ input.imageBase64Bytes ++ input.imageCount * COMPOSER_FILE_ENTRY_METADATA_BYTES)}@@ -86,12 +117,13 @@ export function composerFileAdmissionError(if (context.attachedCount >= COMPOSER_MAX_ATTACHMENTS) {return `A message can carry at most ${COMPOSER_MAX_ATTACHMENTS} attachments.`}- const bodyBytes = composerNonImageBodyBytes({- files: [...context.files, { filename: file.name, sizeBytes: file.size }],- textBytes: context.textBytes,- })+ const files = [...context.files, { filename: file.name, sizeBytes: file.size }]+ if (composerFileBase64Bytes(files) > COMPOSER_MAX_TOTAL_FILE_BASE64_BYTES) {+ return `${file.name} does not fit: the files in a message can take at most ${formatFileSize(COMPOSER_MAX_TOTAL_FILE_BASE64_BYTES)} once encoded.`+ }+ const bodyBytes = composerNonImageBodyBytes({ files, textBytes: context.textBytes })if (bodyBytes > COMPOSER_MAX_NON_IMAGE_BODY_BYTES) {- return `${file.name} does not fit: files and text can take at most ${formatFileSize(COMPOSER_MAX_NON_IMAGE_BODY_BYTES)} per message once encoded.`+ return `${file.name} does not fit: the text and file details can take at most ${formatFileSize(COMPOSER_MAX_NON_IMAGE_BODY_BYTES)} per message once encoded.`}return null}diff --git a/docs/architecture/codex-subscription-transport-contract.md b/docs/architecture/codex-subscription-transport-contract.mdindex f21aa261c..2495e9c07 100644--- a/docs/architecture/codex-subscription-transport-contract.md+++ b/docs/architecture/codex-subscription-transport-contract.md@@ -71,7 +71,9 @@ the shared visual envelope budget refuses to start.Desktop enforces the 16 MiB individual and 16 MiB combined hard attachmentbudgets (usual target remains 5 / 9 MiB).RPC and Host permit a 24 MiB JSON body only on their message POST routes; chat-non-image bytes stay on the 6 MiB share. Non-chat rpc-proxy and Host control+text and envelope bytes stay on the 6 MiB share. Qualifying `kind:'file'`+attachments (at most 11 MiB decoded each) have their own 16 MiB base64 quota,+like images, and everything stays under the 24 MiB body. Non-chat rpc-proxy and Host controlroutes keep the 10 MB ordinary JSON cap. The proxy's largerparser requires a valid platform identity on the visual completion route.Admin and unauthenticated requests retain the ordinary configured body limit.diff --git a/docs/testing/codex-subscription-validation.md b/docs/testing/codex-subscription-validation.mdindex 7ad52928c..708dd8a0f 100644--- a/docs/testing/codex-subscription-validation.md+++ b/docs/testing/codex-subscription-validation.md@@ -15,7 +15,8 @@ per-image / 16 MiB aggregate / 24 MiB envelope ceiling, plus the 2048 pxmodel bound. Exercise 5 MiB, 12 MiB (exceptional, above 10 MiB), 10+5 MiBand 3x5 MiB acceptance, plus overflow above 16 MiB. V1 and V2 non-image fields keep an 8 MiB ceiling(#731), and beside a hard-ceiling image the 24 MiB envelope leaves about 2.7 MiB of non-image data;-chat non-image bytes stay at 6 MiB; unrelated rpc-proxy and Host control routes keep the 10 MB ordinary JSON cap. The larger proxy parser must not admit an+chat text and envelope bytes stay at 6 MiB, while qualifying `kind:'file'` attachments (at most 11 MiB decoded each)+have their own 16 MiB base64 quota under the same 24 MiB body; unrelated rpc-proxy and Host control routes keep the 10 MB ordinary JSON cap. The larger proxy parser must not admit ananonymous, wrong-scope or admin request, or enlarge V1's effective body limit.Changing these budgets does not change OAuth, grants, ticket binding, origins,fallback, or connection selection. Local capacity evidence is separate fromdiff --git a/external-rest-api/src/releaseManifest.ts b/external-rest-api/src/releaseManifest.tsindex 338f898a4..4baa3420e 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.10.0',externalRestApiVersion: '0.1.85',- rpcProxyVersion: '0.1.94',+ rpcProxyVersion: '0.1.95',desktopVersion: '0.10.0',minimumDesktopVersion: '0.1.252',}diff --git a/mcp-host/README.md b/mcp-host/README.mdindex d760f90ad..aaf2e6acc 100644--- a/mcp-host/README.md+++ b/mcp-host/README.md@@ -17,51 +17,51 @@ MCP Host is a Kubernetes-native service that reads Host CRD configuration and pr### Environment Variables-| Variable | Explanation | Canonical example |-| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `CLERUM_DEV_MODE` | Enables local/dev bootstrap mode that bypasses Host CRD discovery and reads host/runtime config from env. | `CLERUM_DEV_MODE=true` |-| `CLERUM_HOST_NAME` | Selects which Host CRD to load in production mode; in non-production fallback it defaults to `dev-host`. | `CLERUM_HOST_NAME=chatllm` |-| `CLERUM_NAMESPACE` | Sets the Kubernetes namespace used for Host and Secret lookup when running in cluster mode. | `CLERUM_NAMESPACE=mcp-host` |-| `CLERUM_SERVER_PORT` | Sets the HTTP listen port for the runtime API server. | `CLERUM_SERVER_PORT=8080` |-| `CLERUM_CONTEXT_MAPPER_URL` | Points to the host-context-controller endpoint used to resolve MCP servers for a context. | `CLERUM_CONTEXT_MAPPER_URL=http://host-context-controller-api-gateway.control-plane.svc.cluster.local:8081` |-| `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL` | Controls polling interval (milliseconds) for MCP server config changes from context mapper. | `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL=30000` |-| `HCC_AUTHORITY_MAX_STALENESS_MS` | Maximum time a previously published MCP fleet may survive an unavailable HCC (default 180000 ms; hard-capped at 600000 ms). It must be greater than `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL` in cluster mode; invalid combinations fail startup. Minikube pins 60000 ms for its deterministic staleness E2E. | `HCC_AUTHORITY_MAX_STALENESS_MS=180000` |-| `CLERUM_HOST_CONFIG` | Provides a full Host spec as JSON in dev mode, overriding provider/model context env composition. | `CLERUM_HOST_CONFIG={"host":"dev-host","contextRef":"dev-context","secretRef":"dev-secret","model":{"provider":"openai","name":"gpt-5.4-mini"}}` |-| `CLERUM_MODEL_PROVIDER` | Chooses the model provider in dev mode when `CLERUM_HOST_CONFIG` is not set. | `CLERUM_MODEL_PROVIDER=openai` |-| `CLERUM_MODEL_NAME` | Overrides the default provider model name in dev mode. Used only when `CLERUM_MODEL_PROVIDER` is also set; an auto-detected provider keeps its default model. | `CLERUM_MODEL_NAME=gpt-5.4-mini` |-| `CLERUM_MCP_SERVERS` | Supplies dev MCP server definitions as JSON so you can run without context mapper. Each entry needs `name`, `contextRef`, `transport`, `enabled`, and a `status` object — a server whose `status.ready` is not `true` is parsed but skipped as "not ready". | `CLERUM_MCP_SERVERS=[{"name":"filesystem","contextRef":"dev-context","transport":{"type":"streamableHttp","url":"http://localhost:3101"},"enabled":true,"status":{"deployed":true,"ready":true}}]` |-| `CLERUM_MCP_TOOL_TIMEOUT_MS` | Per-call timeout passed to MCP SDK `Client.callTool(...)` requests. The effective timeout is still bounded by any caller workflow or snippet step budget. | `CLERUM_MCP_TOOL_TIMEOUT_MS=1500000` |-| `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS` | Maximum total MCP SDK tool-call budget used at the SDK request boundary. Operators may tune it up to the existing workflow step ceiling; invalid values fail closed at runtime. | `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS=1500000` |-| `OPENAI_API_KEY` | OpenAI API key used by dev mode when provider selection resolves to OpenAI. | `OPENAI_API_KEY=sk-xxxx` |-| `CLAUDE_API_KEY` | Anthropic API key used by dev mode when provider selection resolves to Claude. | `CLAUDE_API_KEY=sk-ant-xxxx` |-| `ZAI_API_KEY` | ZAI API key used by dev mode when provider selection resolves to ZAI. | `ZAI_API_KEY=zai-xxxx` |-| `BAILIAN_API_KEY` | Bailian API key used by dev mode when provider selection resolves to Bailian/Qwen. | `BAILIAN_API_KEY=ba-xxxx` |-| `CLERUM_AGENT_TASK_DELAY` | Minimum interval in milliseconds between task dispatches; does not delay individual tool iterations. | `CLERUM_AGENT_TASK_DELAY=3` |-| `CLERUM_AGENT_MAX_TASK_DURATION` | Maximum active task execution time in milliseconds (24 hours), accumulated across approval resumptions. Approval waiting is excluded. | `CLERUM_AGENT_MAX_TASK_DURATION=86400000` |-| `CLERUM_AGENT_MAX_TOOL_CALLS` | Maximum LLM/tool iterations per task; each iteration may call multiple tools. Configured per Host process. | `CLERUM_AGENT_MAX_TOOL_CALLS=1000` |-| `CLERUM_AGENT_MAX_QUEUE_SIZE` | Maximum pending queue size before new tasks are rejected/back-pressured. | `CLERUM_AGENT_MAX_QUEUE_SIZE=100` |-| `CLERUM_ENABLE_APPROVAL` | Enables the approval gate workflow for tool execution decisions. | `CLERUM_ENABLE_APPROVAL=true` |-| `CLERUM_APPROVAL_CONFIG` | JSON config for approval policy/channels when not sourced from Host CRD. | `CLERUM_APPROVAL_CONFIG={"defaultPolicy":"designated_approvers","channels":{"telegram":{"enabled":true,"approvers":["123456"]}}}` |-| `CLERUM_ENABLE_NUDGE` | Enables the nudge controller that pushes model/tool retry guidance when output is rejected. | `CLERUM_ENABLE_NUDGE=false` |-| `CLERUM_NUDGE_MAX_ITERATIONS` | Maximum number of nudge cycles allowed for a task. | `CLERUM_NUDGE_MAX_ITERATIONS=3` |-| `CLERUM_CONTEXT_MAX_TOKENS` | Token budget used by context compaction when the model's allowlist row carries no context window. `codex-subscription` and `grok-subscription` models use 256000 instead; the Host logs `context_window_resolved` with the window and its source. | `CLERUM_CONTEXT_MAX_TOKENS=100000` |-| `CLERUM_COMPACTION_PRE_PRUNE` | Master switch for pre-pruning the history (deduplication, one-lining, JSON truncation, media stripping). It runs only once the history reaches the compaction threshold (80% of the context window), before any compaction tier is chosen, and at history rehydration under the same threshold. On by default; set to `false` to disable every pass at once. | `CLERUM_COMPACTION_PRE_PRUNE=true` |-| `CLERUM_WORKSPACE_PATH` | Base workspace path used by native tools and workspace-aware operations. | `CLERUM_WORKSPACE_PATH=/workspace` |-| `CLERUM_SHELL_TIMEOUT` | Maximum execution time in milliseconds for shell native-tool commands. | `CLERUM_SHELL_TIMEOUT=1500000` |-| `CLERUM_TOOL_TIMEOUT` | Maximum execution time in milliseconds for native tool wrapper calls. This is separate from the MCP SDK request timeout controlled by `CLERUM_MCP_TOOL_TIMEOUT_MS`. | `CLERUM_TOOL_TIMEOUT=1500000` |-| `CLERUM_HTTP_ALLOWLIST` | Comma-separated allowlist of outbound hosts/URLs allowed for HTTP native tools. With an allowlist set, you can also skip per-call approval by adding `tools: { http_request: false }` under `Host.spec.approval` (see Host CRD). | `CLERUM_HTTP_ALLOWLIST=api.github.com,example.com` |-| `CLERUM_ENV_ALLOWLIST` | Comma-separated list of environment variables forwarded into native tool execution contexts. | `CLERUM_ENV_ALLOWLIST=PATH,HOME,USER,SHELL,LANG,TERM` |-| `CLERUM_MEMORY_MAX_SIZE` | Maximum bytes reserved for in-memory native tool buffers/state. | `CLERUM_MEMORY_MAX_SIZE=1048576` |-| `CLERUM_ENABLE_RESPONSE_ATTACHMENTS` | Enables attachment passthrough in runtime responses when tools return supported media. | `CLERUM_ENABLE_RESPONSE_ATTACHMENTS=true` |-| `CLERUM_ATTACHMENT_MAX_COUNT` | Maximum number of attachments returned per response. | `CLERUM_ATTACHMENT_MAX_COUNT=3` |-| `CLERUM_ATTACHMENT_MAX_BYTES` | Maximum decoded size per attachment in bytes (oversized payloads are dropped). | `CLERUM_ATTACHMENT_MAX_BYTES=52428800` |-| `CLERUM_ATTACHMENT_FILE_MAX_BYTES` | Maximum decoded size in bytes of one incoming `kind:'file'` attachment; one larger file rejects the message with `FILE_ATTACHMENT_TOO_LARGE`. File base64 also counts against the 6 MiB non-image body budget, so two files at the 3 MiB default get HTTP 413 before admission. An invalid value stops the Host at startup. | `CLERUM_ATTACHMENT_FILE_MAX_BYTES=3145728` |-| `CLERUM_ATTACHMENT_TEXT_READ_MAX_BYTES` | Maximum bytes one `clerum__attachment_read` call returns; longer text is returned with `truncated:true` and read on with `offset`. An invalid value stops the Host at startup. | `CLERUM_ATTACHMENT_TEXT_READ_MAX_BYTES=262144` |-| `CLERUM_MEMORY_ENABLED` | Enables workspace memory persistence features. | `CLERUM_MEMORY_ENABLED=true` |-| `CLERUM_MEMORY_WORKSPACE_PATH` | Sets workspace directory path used when memory mode is enabled. | `CLERUM_MEMORY_WORKSPACE_PATH=/workspace` |-| `CLERUM_PERSONALIZATION_ENABLED` | Enables identity/personalization seeding behavior. | `CLERUM_PERSONALIZATION_ENABLED=true` |-| `CLERUM_IDENTITY_SEED` | JSON identity seed used to initialize personalization artifacts when enabled. | `CLERUM_IDENTITY_SEED={"displayName":"Clerum Agent","tone":"concise"}` |-| `NODE_ENV` | Influences production checks and defaults (for example strict host-name requirement in production). | `NODE_ENV=production` |+| Variable | Explanation | Canonical example |+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `CLERUM_DEV_MODE` | Enables local/dev bootstrap mode that bypasses Host CRD discovery and reads host/runtime config from env. | `CLERUM_DEV_MODE=true` |+| `CLERUM_HOST_NAME` | Selects which Host CRD to load in production mode; in non-production fallback it defaults to `dev-host`. | `CLERUM_HOST_NAME=chatllm` |+| `CLERUM_NAMESPACE` | Sets the Kubernetes namespace used for Host and Secret lookup when running in cluster mode. | `CLERUM_NAMESPACE=mcp-host` |+| `CLERUM_SERVER_PORT` | Sets the HTTP listen port for the runtime API server. | `CLERUM_SERVER_PORT=8080` |+| `CLERUM_CONTEXT_MAPPER_URL` | Points to the host-context-controller endpoint used to resolve MCP servers for a context. | `CLERUM_CONTEXT_MAPPER_URL=http://host-context-controller-api-gateway.control-plane.svc.cluster.local:8081` |+| `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL` | Controls polling interval (milliseconds) for MCP server config changes from context mapper. | `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL=30000` |+| `HCC_AUTHORITY_MAX_STALENESS_MS` | Maximum time a previously published MCP fleet may survive an unavailable HCC (default 180000 ms; hard-capped at 600000 ms). It must be greater than `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL` in cluster mode; invalid combinations fail startup. Minikube pins 60000 ms for its deterministic staleness E2E. | `HCC_AUTHORITY_MAX_STALENESS_MS=180000` |+| `CLERUM_HOST_CONFIG` | Provides a full Host spec as JSON in dev mode, overriding provider/model context env composition. | `CLERUM_HOST_CONFIG={"host":"dev-host","contextRef":"dev-context","secretRef":"dev-secret","model":{"provider":"openai","name":"gpt-5.4-mini"}}` |+| `CLERUM_MODEL_PROVIDER` | Chooses the model provider in dev mode when `CLERUM_HOST_CONFIG` is not set. | `CLERUM_MODEL_PROVIDER=openai` |+| `CLERUM_MODEL_NAME` | Overrides the default provider model name in dev mode. Used only when `CLERUM_MODEL_PROVIDER` is also set; an auto-detected provider keeps its default model. | `CLERUM_MODEL_NAME=gpt-5.4-mini` |+| `CLERUM_MCP_SERVERS` | Supplies dev MCP server definitions as JSON so you can run without context mapper. Each entry needs `name`, `contextRef`, `transport`, `enabled`, and a `status` object — a server whose `status.ready` is not `true` is parsed but skipped as "not ready". | `CLERUM_MCP_SERVERS=[{"name":"filesystem","contextRef":"dev-context","transport":{"type":"streamableHttp","url":"http://localhost:3101"},"enabled":true,"status":{"deployed":true,"ready":true}}]` |+| `CLERUM_MCP_TOOL_TIMEOUT_MS` | Per-call timeout passed to MCP SDK `Client.callTool(...)` requests. The effective timeout is still bounded by any caller workflow or snippet step budget. | `CLERUM_MCP_TOOL_TIMEOUT_MS=1500000` |+| `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS` | Maximum total MCP SDK tool-call budget used at the SDK request boundary. Operators may tune it up to the existing workflow step ceiling; invalid values fail closed at runtime. | `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS=1500000` |+| `OPENAI_API_KEY` | OpenAI API key used by dev mode when provider selection resolves to OpenAI. | `OPENAI_API_KEY=sk-xxxx` |+| `CLAUDE_API_KEY` | Anthropic API key used by dev mode when provider selection resolves to Claude. | `CLAUDE_API_KEY=sk-ant-xxxx` |+| `ZAI_API_KEY` | ZAI API key used by dev mode when provider selection resolves to ZAI. | `ZAI_API_KEY=zai-xxxx` |+| `BAILIAN_API_KEY` | Bailian API key used by dev mode when provider selection resolves to Bailian/Qwen. | `BAILIAN_API_KEY=ba-xxxx` |+| `CLERUM_AGENT_TASK_DELAY` | Minimum interval in milliseconds between task dispatches; does not delay individual tool iterations. | `CLERUM_AGENT_TASK_DELAY=3` |+| `CLERUM_AGENT_MAX_TASK_DURATION` | Maximum active task execution time in milliseconds (24 hours), accumulated across approval resumptions. Approval waiting is excluded. | `CLERUM_AGENT_MAX_TASK_DURATION=86400000` |+| `CLERUM_AGENT_MAX_TOOL_CALLS` | Maximum LLM/tool iterations per task; each iteration may call multiple tools. Configured per Host process. | `CLERUM_AGENT_MAX_TOOL_CALLS=1000` |+| `CLERUM_AGENT_MAX_QUEUE_SIZE` | Maximum pending queue size before new tasks are rejected/back-pressured. | `CLERUM_AGENT_MAX_QUEUE_SIZE=100` |+| `CLERUM_ENABLE_APPROVAL` | Enables the approval gate workflow for tool execution decisions. | `CLERUM_ENABLE_APPROVAL=true` |+| `CLERUM_APPROVAL_CONFIG` | JSON config for approval policy/channels when not sourced from Host CRD. | `CLERUM_APPROVAL_CONFIG={"defaultPolicy":"designated_approvers","channels":{"telegram":{"enabled":true,"approvers":["123456"]}}}` |+| `CLERUM_ENABLE_NUDGE` | Enables the nudge controller that pushes model/tool retry guidance when output is rejected. | `CLERUM_ENABLE_NUDGE=false` |+| `CLERUM_NUDGE_MAX_ITERATIONS` | Maximum number of nudge cycles allowed for a task. | `CLERUM_NUDGE_MAX_ITERATIONS=3` |+| `CLERUM_CONTEXT_MAX_TOKENS` | Token budget used by context compaction when the model's allowlist row carries no context window. `codex-subscription` and `grok-subscription` models use 256000 instead; the Host logs `context_window_resolved` with the window and its source. | `CLERUM_CONTEXT_MAX_TOKENS=100000` |+| `CLERUM_COMPACTION_PRE_PRUNE` | Master switch for pre-pruning the history (deduplication, one-lining, JSON truncation, media stripping). It runs only once the history reaches the compaction threshold (80% of the context window), before any compaction tier is chosen, and at history rehydration under the same threshold. On by default; set to `false` to disable every pass at once. | `CLERUM_COMPACTION_PRE_PRUNE=true` |+| `CLERUM_WORKSPACE_PATH` | Base workspace path used by native tools and workspace-aware operations. | `CLERUM_WORKSPACE_PATH=/workspace` |+| `CLERUM_SHELL_TIMEOUT` | Maximum execution time in milliseconds for shell native-tool commands. | `CLERUM_SHELL_TIMEOUT=1500000` |+| `CLERUM_TOOL_TIMEOUT` | Maximum execution time in milliseconds for native tool wrapper calls. This is separate from the MCP SDK request timeout controlled by `CLERUM_MCP_TOOL_TIMEOUT_MS`. | `CLERUM_TOOL_TIMEOUT=1500000` |+| `CLERUM_HTTP_ALLOWLIST` | Comma-separated allowlist of outbound hosts/URLs allowed for HTTP native tools. With an allowlist set, you can also skip per-call approval by adding `tools: { http_request: false }` under `Host.spec.approval` (see Host CRD). | `CLERUM_HTTP_ALLOWLIST=api.github.com,example.com` |+| `CLERUM_ENV_ALLOWLIST` | Comma-separated list of environment variables forwarded into native tool execution contexts. | `CLERUM_ENV_ALLOWLIST=PATH,HOME,USER,SHELL,LANG,TERM` |+| `CLERUM_MEMORY_MAX_SIZE` | Maximum bytes reserved for in-memory native tool buffers/state. | `CLERUM_MEMORY_MAX_SIZE=1048576` |+| `CLERUM_ENABLE_RESPONSE_ATTACHMENTS` | Enables attachment passthrough in runtime responses when tools return supported media. | `CLERUM_ENABLE_RESPONSE_ATTACHMENTS=true` |+| `CLERUM_ATTACHMENT_MAX_COUNT` | Maximum number of attachments returned per response. | `CLERUM_ATTACHMENT_MAX_COUNT=3` |+| `CLERUM_ATTACHMENT_MAX_BYTES` | Maximum decoded size per attachment in bytes (oversized payloads are dropped). | `CLERUM_ATTACHMENT_MAX_BYTES=52428800` |+| `CLERUM_ATTACHMENT_FILE_MAX_BYTES` | Maximum decoded size in bytes of one incoming `kind:'file'` attachment; one larger file rejects the message with `FILE_ATTACHMENT_TOO_LARGE`. File base64 has its own 16 MiB quota in the chat body (11 MiB per file at the default), and the message text stays in the 6 MiB non-image share; a lower value here does not lower that quota. An invalid value stops the Host at startup. | `CLERUM_ATTACHMENT_FILE_MAX_BYTES=11534336` |+| `CLERUM_ATTACHMENT_TEXT_READ_MAX_BYTES` | Maximum bytes one `clerum__attachment_read` call returns, and its default page; longer text is returned with `truncated:true` and read on with `offset`. The page is shipped to the model inline (the tool is exempt from `CLERUM_TOOL_SPILLOVER_THRESHOLD`), so size it against `CLERUM_CONTEXT_MAX_TOKENS`: the default is ~16k heuristic tokens, about a fifth of the default compaction budget. An invalid value stops the Host at startup. | `CLERUM_ATTACHMENT_TEXT_READ_MAX_BYTES=65536` |+| `CLERUM_MEMORY_ENABLED` | Enables workspace memory persistence features. | `CLERUM_MEMORY_ENABLED=true` |+| `CLERUM_MEMORY_WORKSPACE_PATH` | Sets workspace directory path used when memory mode is enabled. | `CLERUM_MEMORY_WORKSPACE_PATH=/workspace` |+| `CLERUM_PERSONALIZATION_ENABLED` | Enables identity/personalization seeding behavior. | `CLERUM_PERSONALIZATION_ENABLED=true` |+| `CLERUM_IDENTITY_SEED` | JSON identity seed used to initialize personalization artifacts when enabled. | `CLERUM_IDENTITY_SEED={"displayName":"Clerum Agent","tone":"concise"}` |+| `NODE_ENV` | Influences production checks and defaults (for example strict host-name requirement in production). | `NODE_ENV=production` |### Host CRDdiff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.jsonindex fa85fc3a0..9feb4321f 100644--- a/mcp-host/package-lock.json+++ b/mcp-host/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-mcp-host",- "version": "0.1.471",+ "version": "0.1.472","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-mcp-host",- "version": "0.1.471",+ "version": "0.1.472","license": "SEE LICENSE IN LICENSE","dependencies": {"@anthropic-ai/sdk": "^0.32.0",diff --git a/mcp-host/package.json b/mcp-host/package.jsonindex 2313280cd..07681f4d1 100644--- a/mcp-host/package.json+++ b/mcp-host/package.json@@ -1,6 +1,6 @@{"name": "clerum-mcp-host",- "version": "0.1.471",+ "version": "0.1.472","description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude","main": "dist/main.js","engines": {diff --git a/mcp-host/src/__tests__/bodylimits.test.ts b/mcp-host/src/__tests__/bodylimits.test.tsindex 13d2c2322..07d64cc6d 100644--- a/mcp-host/src/__tests__/bodylimits.test.ts+++ b/mcp-host/src/__tests__/bodylimits.test.ts@@ -7,6 +7,8 @@* of being rejected as too large.* - The attachments arrive byte-identical: nothing is dropped, truncated or* re-encoded on the way through the parser.+ * - Qualifying `kind:'file'` attachments have their own credited quota+ * (11MiB decoded per file, 16MiB of base64 in total, issue #678).* - The larger ceiling is NOT a general text allowance: non-image bytes stay* capped at 6MiB. Every other Host route keeps the 10mb ordinary JSON* parser, matching rpc-proxy `jsonBody`.@@ -281,7 +283,7 @@ describe('mcp-host runtime message body budget', () => {expect(captured).toHaveLength(0)})- describe('kind:file attachments count against the 6MiB non-image budget (issue #666)', () => {+ describe('kind:file attachments without the composer wire shape (issue #666)', () => {const NON_IMAGE_BUDGET = 6 * MIBconst KIB = 1024@@ -321,40 +323,234 @@ describe('mcp-host runtime message body budget', () => {expect(captured[0]!.attachments?.[0]?.dataBase64.length).toBe(dataBase64.length)})- it('rejects a file body 1KiB over the budget with 413', async () => {+ it('charges a file body without a digest to the non-image budget', async () => {+ // A file without the composer's sha256 digest is never credited to the+ // file quota, so its base64 counts against the 6MiB share.+ const withoutDigest = (targetBytes: number) => {+ const { payload, dataBase64 } = fileMessageOfBodySize(targetBytes)+ const { digest: _digest, ...attachment } = fileAttachment(dataBase64)+ return { ...payload, attachments: [attachment] }+ }captured = []// Control: the same construction under the budget is delivered.- const under = fileMessageOfBodySize(NON_IMAGE_BUDGET - KIB)- expect((await postMessage(under.payload)).status).toBe(200)+ expect((await postMessage(withoutDigest(NON_IMAGE_BUDGET - KIB))).status).toBe(200)+ expect(captured).toHaveLength(1)+ captured = []+ const response = await postMessage(withoutDigest(NON_IMAGE_BUDGET + KIB))+ expect(response.status).toBe(413)+ expect(captured).toHaveLength(0)+ })+ })++ describe('kind:file attachments have their own credited quota (issue #678)', () => {+ const FILE_MAX_BYTES = 11 * MIB+ const FILE_QUOTA_BASE64 = 16 * MIB+ const NON_IMAGE_BUDGET = 6 * MIB+ const KIB = 1024+ const fileBase64Cache = new Map<number, string>()++ /** Canonical base64 of `sizeBytes` bytes of ASCII text. */+ function textFileBase64(sizeBytes: number): string {+ return cachedBase64(fileBase64Cache, Buffer.alloc(sizeBytes, 0x61), sizeBytes)+ }++ function textFile(id: string, sizeBytes: number) {+ return {+ id,+ kind: 'file' as const,+ mimeType: 'text/plain',+ detectedMediaType: 'text/plain',+ encoding: 'base64' as const,+ dataBase64: textFileBase64(sizeBytes),+ filename: `${id}.txt`,+ sizeBytes,+ digest: { algorithm: 'sha256' as const, hex: 'ab'.repeat(32) },+ }+ }++ /**+ * A message whose body minus the base64 of `attachments` is exactly+ * `shareBytes`: the bytes the 6MiB share is charged when every file is+ * credited.+ */+ function messageWithShare(attachments: Array<{ dataBase64: string }>, shareBytes: number) {+ const base64Bytes = attachments.reduce((total, item) => total + item.dataBase64.length, 0)+ const empty = { ...messagePayload(attachments), content: '' }+ const overhead = Buffer.byteLength(JSON.stringify(empty)) - base64Bytes+ const payload = { ...empty, content: 'x'.repeat(shareBytes - overhead) }+ expect(Buffer.byteLength(JSON.stringify(payload)) - base64Bytes).toBe(shareBytes)+ return payload+ }++ function deliveredAttachmentIds(): unknown[] {+ expect(captured).toHaveLength(1)+ return (captured[0]!.attachments ?? []).map(item => item.id)+ }++ it('delivers an 11MiB file beside a text share 1KiB under 6MiB byte-identical', async () => {captured = []- const response = await postMessage(fileMessageOfBodySize(NON_IMAGE_BUDGET + KIB).payload)+ const file = textFile('f1', FILE_MAX_BYTES)+ const payload = messageWithShare([file], NON_IMAGE_BUDGET - KIB)+ // The whole body is far past the 6MiB share: only the file credit lets it through.+ expect(Buffer.byteLength(JSON.stringify(payload))).toBeGreaterThan(20 * MIB)+ const response = await postMessage(payload)+ expect(response.status).toBe(200)+ expect(deliveredAttachmentIds()).toEqual(['f1'])+ expect(captured[0]!.attachments?.[0]?.dataBase64).toBe(file.dataBase64)+ })++ it('rejects an 11MiB file when the text share is 1KiB over 6MiB', async () => {+ const file = textFile('f1', FILE_MAX_BYTES)+ captured = []+ expect((await postMessage(messageWithShare([file], NON_IMAGE_BUDGET - KIB))).status).toBe(200)+ expect(captured).toHaveLength(1)+ captured = []+ const response = await postMessage(messageWithShare([file], NON_IMAGE_BUDGET + KIB))expect(response.status).toBe(413)expect(captured).toHaveLength(0)})- it('never credits PNG bytes sent as kind:file against the image budget', async () => {- const dataBase64 = pngBase64(7 * MIB)+ it('decides the 11MiB limit by decoded bytes, not by base64 length', async () => {+ const atLimit = textFile('f1', FILE_MAX_BYTES)+ const overLimit = textFile('f1', FILE_MAX_BYTES + 1)+ // Both encode to the same number of characters; only the padding differs.+ expect(overLimit.dataBase64.length).toBe(atLimit.dataBase64.length)captured = []- const asImage = await postMessage(- messagePayload([{ ...imageAttachment('a1', 7 * MIB), dataBase64 }])+ expect((await postMessage(messageWithShare([atLimit], KIB))).status).toBe(200)+ expect(captured).toHaveLength(1)+ captured = []+ const response = await postMessage(messageWithShare([overLimit], KIB))+ expect(response.status).toBe(413)+ expect(captured).toHaveLength(0)+ })++ it('does not credit file base64 whose padding carries non-zero unused bits', async () => {+ const canonical = textFile('f1', FILE_MAX_BYTES)+ const nonCanonical = {+ ...canonical,+ dataBase64: withNonCanonicalTailBits(canonical.dataBase64),+ }+ captured = []+ expect((await postMessage(messageWithShare([canonical], KIB))).status).toBe(200)+ expect(captured).toHaveLength(1)+ captured = []+ const response = await postMessage(messageWithShare([nonCanonical], KIB))+ expect(response.status).toBe(413)+ expect(captured).toHaveLength(0)+ })++ it.each([+ { label: 'no digest', mutate: ({ digest: _d, ...rest }: Record<string, unknown>) => rest },+ {+ label: 'a sha1 digest',+ mutate: (item: Record<string, unknown>) => ({+ ...item,+ digest: { algorithm: 'sha1', hex: 'ab'.repeat(32) },+ }),+ },+ {+ label: 'an uppercase digest',+ mutate: (item: Record<string, unknown>) => ({+ ...item,+ digest: { algorithm: 'sha256', hex: 'AB'.repeat(32) },+ }),+ },+ {+ label: 'a raw encoding',+ mutate: (item: Record<string, unknown>) => ({ ...item, encoding: 'raw' }),+ },+ {+ label: 'an empty file name',+ mutate: (item: Record<string, unknown>) => ({ ...item, filename: '' }),+ },+ {+ label: 'no file name',+ mutate: ({ filename: _f, ...rest }: Record<string, unknown>) => rest,+ },+ ])('charges a 5MiB file with $label to the non-image budget', async ({ mutate }) => {+ // 5MiB encodes to about 6.7MiB: credited it fits, charged as text it does not.+ const complete = textFile('f1', 5 * MIB)+ captured = []+ expect((await postMessage(messageWithShare([complete], KIB))).status).toBe(200)+ expect(captured).toHaveLength(1)+ captured = []+ const response = await postMessage(messagePayload([mutate(complete)]))+ expect(response.status).toBe(413)+ expect(captured).toHaveLength(0)+ })++ it('delivers files that sit exactly on the 16MiB base64 quota and rejects one byte past it', async () => {+ const large = textFile('f1', FILE_MAX_BYTES)+ const fitting = textFile('f2', MIB - 1)+ const overflowing = textFile('f2', MIB)+ expect(large.dataBase64.length + fitting.dataBase64.length).toBe(FILE_QUOTA_BASE64)+ expect(large.dataBase64.length + overflowing.dataBase64.length).toBeGreaterThan(+ FILE_QUOTA_BASE64)+ captured = []+ const ok = await postMessage(messageWithShare([large, fitting], KIB))+ expect(ok.status).toBe(200)+ expect(deliveredAttachmentIds()).toEqual(['f1', 'f2'])+ captured = []+ const response = await postMessage(messageWithShare([large, overflowing], KIB))+ expect(response.status).toBe(413)+ expect(captured).toHaveLength(0)+ })++ it('credits PNG bytes sent as kind:file to the file quota, up to 11MiB', async () => {+ const pngAsFile = (sizeBytes: number) => ({+ ...textFile('f1', 1),+ dataBase64: pngBase64(sizeBytes),+ mimeType: 'image/png',+ detectedMediaType: 'image/png',+ filename: 'photo.png',+ sizeBytes,+ })+ captured = []+ const small = await postMessage(messagePayload([pngAsFile(7 * MIB)]))+ expect(small.status).toBe(200)+ expect(deliveredAttachmentIds()).toEqual(['f1'])+ captured = []+ // The same 12MiB bytes are credited as an image (16MiB limit)…+ const asImage = await postMessage(messagePayload([imageAttachment('a1', 12 * MIB)]))expect(asImage.status).toBe(200)expect(captured).toHaveLength(1)captured = []- // Same MIME type and bytes as the image: only `kind` differs.- const asFile = await postMessage(- messagePayload([- {- ...fileAttachment(dataBase64),- mimeType: 'image/png',- detectedMediaType: 'image/png',- filename: 'photo.png',- },- ])- )+ // …but not as a file, whose limit is 11MiB.+ const asFile = await postMessage(messagePayload([pngAsFile(12 * MIB)]))expect(asFile.status).toBe(413)expect(captured).toHaveLength(0)})++ it('delivers an 11MiB file beside a 5MiB image and rejects the pair past 24MiB', async () => {+ const file = textFile('f1', FILE_MAX_BYTES)+ const fits = messagePayload([file, imageAttachment('a1', 5 * MIB)])+ expect(Buffer.byteLength(JSON.stringify(fits))).toBeLessThan(24 * MIB)+ captured = []+ expect((await postMessage(fits)).status).toBe(200)+ expect(deliveredAttachmentIds()).toEqual(['f1', 'a1'])+ captured = []+ const tooBig = messagePayload([file, imageAttachment('a1', 8 * MIB)])+ expect(Buffer.byteLength(JSON.stringify(tooBig))).toBeGreaterThan(24 * MIB)+ const response = await postMessage(tooBig)+ expect(response.status).toBe(413)+ expect(captured).toHaveLength(0)+ })++ it('credits twenty files and rejects a twenty-first instead of charging it as text', async () => {+ const files = (count: number) =>+ Array.from({ length: count }, (_, index) => textFile(`f${index + 1}`, KIB))+ captured = []+ const twenty = await postMessage(messagePayload(files(20)))+ expect(twenty.status).toBe(200)+ expect(deliveredAttachmentIds()).toHaveLength(20)+ captured = []+ const body = messagePayload(files(21))+ expect(Buffer.byteLength(JSON.stringify(body))).toBeLessThan(NON_IMAGE_BUDGET)+ const response = await postMessage(body)+ expect(response.status).toBe(413)+ expect(captured).toHaveLength(0)+ })})it('rejects a body past the 24MiB ceiling', async () => {diff --git a/mcp-host/src/agent/__tests__/incomingAttachments.test.ts b/mcp-host/src/agent/__tests__/incomingAttachments.test.tsindex f15fdeb97..27e458698 100644--- a/mcp-host/src/agent/__tests__/incomingAttachments.test.ts+++ b/mcp-host/src/agent/__tests__/incomingAttachments.test.ts@@ -407,6 +407,25 @@ describe('file attachment validation (issue #666)', () => {expect(result).not.toHaveProperty('attachments')})+ it('bounds a file by decoded bytes when one byte more has the same base64 length (#678)', () => {+ // 11 and 12 bytes both encode to 16 characters, like 11MiB and 11MiB + 1.+ const boundary = { maxCount: 2, maxBytes: 10, maxFileBytes: 11, messageId: 'message-1' }+ const atLimit = fileOf('x'.repeat(11), 'at-limit.txt', 'text/plain', 'text/plain')+ const overLimit = fileOf('x'.repeat(12), 'over-limit.txt', 'text/plain', 'text/plain')+ expect(overLimit.dataBase64.length).toBe(atLimit.dataBase64.length)++ const admitted = validateIncomingAttachments([atLimit], boundary)+ expect(admitted.ok && admitted.attachments?.map(item => item.sizeBytes)).toEqual([11])++ for (const declared of [12, 11]) {+ const rejected = validateIncomingAttachments(+ [{ ...overLimit, sizeBytes: declared }],+ boundary+ )+ expect(rejected).toMatchObject({ ok: false, error: { code: 'FILE_ATTACHMENT_TOO_LARGE' } })+ }+ })+it('keeps the #669 rejection for an unknown kind', () => {const result = validateIncomingAttachments([{ ...notes, kind: 'document' }], limits)expect(result).toMatchObject({ ok: false, error: { code: 'LLM_INVALID_ATTACHMENT' } })diff --git a/mcp-host/src/agent/incomingAttachments.ts b/mcp-host/src/agent/incomingAttachments.tsindex 34d584505..51ead410b 100644--- a/mcp-host/src/agent/incomingAttachments.ts+++ b/mcp-host/src/agent/incomingAttachments.ts@@ -17,12 +17,13 @@ import type { TaskError } from '../queue/types'* Attachments (images and files together) accepted in one incoming message.* Kept separate from `CLERUM_ATTACHMENT_MAX_COUNT`, which caps the attachments* a response returns.- * Must match COMPOSER_MAX_IMAGE_ATTACHMENTS in desktop-app/ui/src/constants/attachments.ts.+ * Must match COMPOSER_MAX_ATTACHMENTS in desktop-app/ui/src/constants/attachments.ts.* Per-image bytes stay on the channel `attachmentMaxBytes` (issue #654 / PR* #669) — this module must not clamp general inbound traffic to the Codex* `VISUAL_LIMITS`. The Codex chat hop is a separate 24 MiB parser with a- * 16 MiB credited image budget. Per-file bytes use `attachmentFileMaxBytes`- * (issue #666). This count is the fail-loud admission cap.+ * 16 MiB credited image budget and a 16 MiB credited file budget. Per-file+ * bytes use `attachmentFileMaxBytes` (issue #666, 11 MiB by default per issue+ * #678). This count is the fail-loud admission cap.*/export const INCOMING_ATTACHMENT_MAX_COUNT = 20diff --git a/mcp-host/src/agent/taskExecutor.ts b/mcp-host/src/agent/taskExecutor.tsindex abc48c9a7..287b5db96 100644--- a/mcp-host/src/agent/taskExecutor.ts+++ b/mcp-host/src/agent/taskExecutor.ts@@ -2054,12 +2054,7 @@ export class TaskExecutor {this.deps.failover?.policy.fallbacks)const nativeRegistry = new NativeToolRegistry(- // The spillover threshold is a top-level setting; clerum__attachment_read- // states it in its description (#666).- {- ...appConfig.nativeTool,- toolSpilloverThresholdBytes: appConfig.toolSpilloverThresholdBytes,- },+ appConfig.nativeTool,this.conversation!.id,this.deps.cronScheduler ?? undefined,this.task.sourceMessage,diff --git a/mcp-host/src/config.fileIngress.test.ts b/mcp-host/src/config.fileIngress.test.tsindex 66affb0eb..8740b93a4 100644--- a/mcp-host/src/config.fileIngress.test.ts+++ b/mcp-host/src/config.fileIngress.test.ts@@ -37,6 +37,44 @@ describe('#666 file ingress configuration', () => {})+ it('defaults the per-file attachment limit to 11MiB, the parser file quota (#678)', async () => {+ vi.resetModules()+ // Precondition: the default is what is under test, so the variable must be unset.+ expect(process.env.CLERUM_ATTACHMENT_FILE_MAX_BYTES).toBeUndefined()+ const { config } = await import('./config')+ expect(config.attachmentFileMaxBytes).toBe(11_534_336)+ })++ it('defaults the attachment text page to 64 KiB, under a quarter of the default compaction budget', async () => {+ vi.resetModules()+ // Precondition: the default is what is under test, so the variable must be unset.+ expect(process.env.CLERUM_ATTACHMENT_TEXT_READ_MAX_BYTES).toBeUndefined()+ const { config } = await import('./config')+ expect(config.attachmentTextReadMaxBytes).toBe(65_536)+ expect(config.nativeTool.attachmentTextReadMaxBytes).toBe(65_536)+ // The page is inline, so it is measured against the context budget, not+ // the spillover threshold: bytes / 4 heuristic tokens, 0.8 pressure.+ expect(Math.ceil(65_536 / 4)).toBeLessThanOrEqual(0.8 * config.contextMaxTokens * 0.25)+ })++ it.each(['0', 'abc', '2147483648'])(+ 'rejects a per-file attachment limit of %j at config load, naming the variable',+ async value => {+ vi.resetModules()+ vi.stubEnv('CLERUM_ATTACHMENT_FILE_MAX_BYTES', value)+ await expect(import('./config')).rejects.toThrow(+ 'CLERUM_ATTACHMENT_FILE_MAX_BYTES must be a valid bounded integer'+ )+ }+ )++ it('loads an explicit per-file attachment limit', async () => {+ vi.resetModules()+ vi.stubEnv('CLERUM_ATTACHMENT_FILE_MAX_BYTES', '3145728')+ const { config } = await import('./config')+ expect(config.attachmentFileMaxBytes).toBe(3_145_728)+ })+it('loads an explicit spillover threshold', async () => {vi.resetModules()vi.stubEnv(SPILLOVER, '16384')diff --git a/mcp-host/src/config.ts b/mcp-host/src/config.tsindex 66de689af..a03284b51 100644--- a/mcp-host/src/config.ts+++ b/mcp-host/src/config.ts@@ -240,7 +240,11 @@ export interface Config {enableResponseAttachments: booleanattachmentMaxCount: numberattachmentMaxBytes: number- /** Decoded bytes per incoming `kind:'file'` attachment (issue #666). */+ /**+ * Decoded bytes per incoming `kind:'file'` attachment (issue #666). The+ * default (11 MiB) matches the file quota of the chat body parser in+ * `server.ts` and rpc-proxy (issue #678).+ */attachmentFileMaxBytes: number/** Bytes one `clerum__attachment_read` call may return (issue #666). */attachmentTextReadMaxBytes: number@@ -499,10 +503,13 @@ function buildDevHostConfig(provider?: LlmProvider, modelName?: string): HostSpeconst devMode = getEnvBool('CLERUM_DEV_MODE', false)// Read once: the top-level field documents the limit, `nativeTool` carries it-// to `clerum__attachment_read` (#666).+// to `clerum__attachment_read` (#666). A page is shipped inline (the tool is+// spillover-exempt), so the default is sized against the context budget: at+// the tokenizer heuristic of 4 bytes per token, 65_536 bytes is ~16k tokens,+// about a fifth of the default compaction budget (0.8 * contextMaxTokens).const attachmentTextReadMaxBytes = getExecutionLimit('CLERUM_ATTACHMENT_TEXT_READ_MAX_BYTES',- 262_144+ 65_536)const configuredWorkflowEnabled = getEnvBool('CLERUM_WORKFLOW_ENABLED', false)const configuredRuntimeKind = resolveMcpHostRuntimeKind({@@ -1035,7 +1042,7 @@ export const config: Config = {enableResponseAttachments: getEnvBool('CLERUM_ENABLE_RESPONSE_ATTACHMENTS', true),attachmentMaxCount: parseInt(getEnv('CLERUM_ATTACHMENT_MAX_COUNT', '3')!, 10),attachmentMaxBytes: parseInt(getEnv('CLERUM_ATTACHMENT_MAX_BYTES', '52428800')!, 10),- attachmentFileMaxBytes: getExecutionLimit('CLERUM_ATTACHMENT_FILE_MAX_BYTES', 3_145_728),+ attachmentFileMaxBytes: getExecutionLimit('CLERUM_ATTACHMENT_FILE_MAX_BYTES', 11_534_336),attachmentTextReadMaxBytes,fileReferenceMaxCount: FILE_REFERENCE_MAX_COUNT,activityBufferSize: parseInt(getEnv('MCP_HOST_ACTIVITY_BUFFER_SIZE', '1000')!, 10),diff --git a/mcp-host/src/core/interfaces.ts b/mcp-host/src/core/interfaces.tsindex f06ba3954..2663e6d01 100644--- a/mcp-host/src/core/interfaces.ts+++ b/mcp-host/src/core/interfaces.ts@@ -115,6 +115,14 @@ export interface Tool {supportsProgressOutput?(): boolean/** Local implementation-owned bounded cleanup after execution is stopped. */timeoutCleanupMs?(): number+ /**+ * Optional. Return true when the tool's output is bounded by its own+ * contract (the caller chose the page, or the output is a blob already+ * spilled once), so the tool loop ships it inline instead of replacing it+ * with a spillover summary. Tools that do not opt in are spilled at the+ * configured threshold.+ */+ spilloverExempt?(): boolean}// ─── Channel ────────────────────────────────────────────────@@ -252,11 +260,9 @@ export interface NativeToolConfig {/** Cron×stateless (CLERUM_STATELESS_LIFECYCLE): steers the cron_manage* stateless notice. Optional so existing construction sites stay valid. */statelessLifecycle?: boolean- /** Per-call byte ceiling of `clerum__attachment_read` (#666). Registering the- * tool for a message with `kind:'file'` attachments requires it. */+ /** Per-call byte ceiling and default page of `clerum__attachment_read`+ * (#666). Registering the tool for a message with `kind:'file'` attachments+ * requires it. Pages are shipped inline, so the value is measured against+ * the context budget, not the spillover threshold. */attachmentTextReadMaxBytes?: number- /** Result size at which the tool loop spills a tool result- * (`CLERUM_TOOL_SPILLOVER_THRESHOLD`). `clerum__attachment_read` states it in- * its description, so registering that tool requires it too (#666). */- toolSpilloverThresholdBytes?: number}diff --git a/mcp-host/src/core/orchestration/__tests__/toolUseLoop.spillover.test.ts b/mcp-host/src/core/orchestration/__tests__/toolUseLoop.spillover.test.tsindex 7f01e2c13..ce37ed697 100644--- a/mcp-host/src/core/orchestration/__tests__/toolUseLoop.spillover.test.ts+++ b/mcp-host/src/core/orchestration/__tests__/toolUseLoop.spillover.test.ts@@ -233,6 +233,23 @@ describe('executeSingleTool — T1.5 spillover wiring', () => {expect(result.spillover_ref).toBeUndefined()})+ it('never spills a tool that declares spilloverExempt, whatever its name', async () => {+ const big = 'X'.repeat(512)+ const exempt: Tool = { ...tool('file_read', big), spilloverExempt: () => true }+ const result = await executeSingleTool(+ { id: 'call-1', name: 'file_read', arguments: {} },+ configFor({ tools: [exempt], storage, taskId: 'taskA' })+ )+ expect(result.content).toBe(big)+ expect(result.spillover_ref).toBeUndefined()+ // Witness: the same output from a tool without the declaration spills.+ const control = await executeSingleTool(+ { id: 'call-2', name: 'file_read', arguments: {} },+ configFor({ tools: [tool('file_read', big)], storage, taskId: 'taskA' })+ )+ expect(control.spillover_ref).toBe('spillover://taskA/call-2.json')+ })+it('skips spillover entirely when storage is undefined (pre-T1.5 behavior)', async () => {const big = 'X'.repeat(512)const result = await executeSingleTool(diff --git a/mcp-host/src/core/orchestration/__tests__/toolUseLoopSingleTool.attachmentRead.test.ts b/mcp-host/src/core/orchestration/__tests__/toolUseLoopSingleTool.attachmentRead.test.tsindex ab822c25a..935ca6066 100644--- a/mcp-host/src/core/orchestration/__tests__/toolUseLoopSingleTool.attachmentRead.test.ts+++ b/mcp-host/src/core/orchestration/__tests__/toolUseLoopSingleTool.attachmentRead.test.ts@@ -1,9 +1,9 @@/**- * #666 — `clerum__attachment_read` pages through `executeSingleTool` with the- * real tool, safety and `SpilloverStorage`. Spillover keeps the first and last- * 400 characters of the serialized result, so a spilled page must still show- * the model its paging fields in `head`; a page under the threshold stays- * inline and writes nothing to disk.+ * #666 / #678 — `clerum__attachment_read` pages through `executeSingleTool`+ * with the real tool, safety and `SpilloverStorage`. The tool bounds its own+ * output (the caller chose the page), so the loop ships every page inline+ * and never replaces it with a spillover summary, whatever the threshold. A+ * control tool of the same size proves the storage is live.*/import { afterEach, beforeEach, describe, expect, it } from 'vitest'import { createHash } from 'node:crypto'@@ -12,19 +12,20 @@ import * as os from 'node:os'import * as path from 'node:path'import { validateIncomingAttachments } from '../../../agent/incomingAttachments'import type { IncomingMessage } from '../../../server'-import type { ToolRegistry } from '../../interfaces'+import type { Tool, ToolRegistry } from '../../interfaces'import { BasicSafety } from '../../safety/safety'import { DefaultToolOutputProcessor } from '../../safety/toolOutputProcessor'-import { SpilloverStorage, type SpilloverSummary } from '../../spillover'+import { SpilloverStorage } from '../../spillover'import { AttachmentReadTool } from '../../tools/attachmentRead'+import type { ToolOutput } from '../../types'+import type { AgentEvent } from '../../types'import { SimpleEventEmitter } from '../eventEmitter'import { executeSingleTool } from '../toolUseLoop'const THRESHOLD = 8192const PAGE_BYTES = 20 * 1024+const READ_LIMIT = 65_536const TASK_ID = 'attachment-task'-// Desktop sends UUID message and attachment ids; the reference id embeds both-// plus the sha256, so these are the lengths the summary head has to hold.const MESSAGE_ID = '6f1c2a9e-4b7d-4c1e-9a53-2f8e7d6c5b4a'const ATTACHMENT_ID = 'c3d9e8f7-1a2b-4c5d-8e9f-0a1b2c3d4e5f'// `sanitized` reports whether redaction changed the output; plain notes do not.@@ -52,23 +53,58 @@ function attachedFile(bytes: Buffer) {return result.attachments![0]!}-/** The page text as it appears inside the serialized result. */-function serializedText(text: string): string {- return JSON.stringify(text).slice(1, -1)+interface InlinePage {+ attachmentId: string+ kind: string+ byteRange: { offset: number; length: number }+ truncated: boolean+ text: string}-describe('executeSingleTool — clerum__attachment_read and the spillover threshold (#666)', () => {+/** The page as the model receives it: the wrapper is present and the body parses. */+function unwrap(content: string): InlinePage {+ expect(content.startsWith(WRAPPER_OPEN)).toBe(true)+ expect(content.endsWith(WRAPPER_CLOSE)).toBe(true)+ return JSON.parse(content.slice(WRAPPER_OPEN.length, -WRAPPER_CLOSE.length)) as InlinePage+}++/** A sanitized tool with no paging contract: the loop's regular spillover path. */+function unboundedTool(name: string, output: string): Tool {+ return {+ name: () => name,+ description: () => `Mock ${name}`,+ parametersSchema: () => ({ type: 'object', properties: {} }),+ requiresSanitization: () => true,+ requiresApproval: () => false,+ execute: async (): Promise<ToolOutput> => ({+ content: output,+ duration_ms: 1,+ is_error: false,+ }),+ }+}++describe('executeSingleTool — clerum__attachment_read pages stay inline (#666, #678)', () => {let workspace: stringlet storage: SpilloverStorage+ let events: SimpleEventEmitter+ let emitted: AgentEvent[]beforeEach(async () => {- workspace = await fs.mkdtemp(path.join(os.tmpdir(), 'attachment-read-spill-'))+ workspace = await fs.mkdtemp(path.join(os.tmpdir(), 'attachment-read-inline-'))storage = new SpilloverStorage({workspacePath: workspace,thresholdBytes: THRESHOLD,ttlMs: 60_000,gcIntervalMs: 0,})+ events = new SimpleEventEmitter()+ emitted = []+ const record = (event: AgentEvent) => {+ emitted.push(event)+ }+ events.on('tool:completed', record)+ events.on('spillover:persisted', record)})afterEach(async () => {@@ -76,22 +112,7 @@ describe('executeSingleTool — clerum__attachment_read and the spillover threshawait fs.rm(workspace, { recursive: true, force: true })})- async function readPage(- attachment: ReturnType<typeof attachedFile>,- callId: string,- args: Record<string, unknown>- ) {- const message: IncomingMessage = {- content: 'Analyze the attached file',- channelType: 'rpc',- channelId: 'agent-1',- sender: 'user-1',- timestamp: '2026-09-24T10:00:00Z',- messageId: MESSAGE_ID,- hostRef: 'host-1',- attachments: [attachment],- }- const tool = new AttachmentReadTool(message, 262_144, THRESHOLD)+ function run(tool: Tool, callId: string, args: Record<string, unknown>) {const registry: ToolRegistry = {get: name => (name === tool.name() ? tool : null),listDefinitions: () => [],@@ -99,16 +120,12 @@ describe('executeSingleTool — clerum__attachment_read and the spillover thresh}const safety = new BasicSafety()return executeSingleTool(- {- id: callId,- name: 'clerum__attachment_read',- arguments: { attachmentId: ATTACHMENT_ID, ...args },- },+ { id: callId, name: tool.name(), arguments: args },{toolRegistry: registry,toolOutputProcessor: new DefaultToolOutputProcessor(safety),safety,- events: new SimpleEventEmitter(),+ events,toolTimeout: 1000,progressReporter: undefined,toolProgressInterval: 0,@@ -118,79 +135,110 @@ describe('executeSingleTool — clerum__attachment_read and the spillover thresh)}- it('spills a 20 KB page into a summary whose head carries the paging fields', async () => {+ function readerFor(attachment: ReturnType<typeof attachedFile>): AttachmentReadTool {+ const message: IncomingMessage = {+ content: 'Analyze the attached file',+ channelType: 'rpc',+ channelId: 'agent-1',+ sender: 'user-1',+ timestamp: '2026-09-24T10:00:00Z',+ messageId: MESSAGE_ID,+ hostRef: 'host-1',+ attachments: [attachment],+ }+ return new AttachmentReadTool(message, READ_LIMIT)+ }++ function eventTypes(): string[] {+ return emitted.map(event => event.type)+ }++ it('ships a 20 KiB page inline, above the spillover threshold, and writes nothing to disk', async () => {const fileText = 'line of notes\n'.repeat(3000)const attachment = attachedFile(Buffer.from(fileText))- const pageText = fileText.slice(0, PAGE_BYTES)- const result = await readPage(attachment, 'read-1', { maxBytes: PAGE_BYTES })+ const result = await run(readerFor(attachment), 'read-1', {+ attachmentId: ATTACHMENT_ID,+ maxBytes: PAGE_BYTES,+ })expect(result.is_error).toBe(false)- expect(result.spillover_ref).toBe(`spillover://${TASK_ID}/read-1.json`)- const summary = JSON.parse(result.content) as SpilloverSummary- expect(summary.byte_size).toBeGreaterThan(PAGE_BYTES)- // The model sees the result inside the tool_output wrapper.- expect(summary.head.startsWith(`${WRAPPER_OPEN}{"attachmentId":"${ATTACHMENT_ID}"`)).toBe(true)- expect(summary.head).toContain(`"referenceId":"${attachment.fileReference!.id}"`)- expect(summary.head).toContain('"kind":"text"')- expect(summary.head).toContain(`"byteRange":{"offset":0,"length":${PAGE_BYTES}}`)- expect(summary.head).toContain('"truncated":true')- // Witness that head reached the text field: every paging field precedes it.- expect(summary.head).toContain('"text":"')- expect(summary.tail).toContain(serializedText(pageText).slice(-100))- expect(summary.tail.endsWith(`"}${WRAPPER_CLOSE}`)).toBe(true)- // What the model is told about the content: plain text with no hint.- expect(summary.content_type).toBe('text/plain')- expect(summary.structure_hint).toBeNull()-- // The spilled blob keeps the page and the reference id; it never holds- // the attachment's base64 or the file name.- const blob = await storage.load(result.spillover_ref!)- expect(blob?.content).toContain(serializedText(pageText))- expect(blob?.content).toContain(attachment.fileReference!.id)- expect(blob?.content).not.toContain(attachment.dataBase64)- expect(blob?.content).not.toContain('notes.txt')+ // Witness: the page itself reached the model, with every paging field.+ const page = unwrap(result.content)+ expect(page.attachmentId).toBe(ATTACHMENT_ID)+ expect(page.kind).toBe('text')+ expect(page.byteRange).toEqual({ offset: 0, length: PAGE_BYTES })+ expect(page.truncated).toBe(true)+ expect(page.text).toBe(fileText.slice(0, PAGE_BYTES))+ expect(Buffer.byteLength(result.content, 'utf8')).toBeGreaterThan(THRESHOLD)+ expect(result.spillover_ref).toBeUndefined()+ // Witness for the negative assertions: the call completed and the loop+ // emitted its completion event; the spillover event did not follow it.+ expect(eventTypes()).toContain('tool:completed')+ expect(eventTypes()).not.toContain('spillover:persisted')+ await expect(fs.access(path.join(workspace, 'spillover', TASK_ID))).rejects.toMatchObject({+ code: 'ENOENT',+ })})- it('reports truncated:false in the head of the last spilled page', async () => {+ it('ships the last page inline with truncated:false', async () => {const fileText = 'line of notes\n'.repeat(2200)const bytes = Buffer.from(fileText)const attachment = attachedFile(bytes)- const result = await readPage(attachment, 'read-2', {+ const result = await run(readerFor(attachment), 'read-2', {+ attachmentId: ATTACHMENT_ID,offset: PAGE_BYTES,maxBytes: PAGE_BYTES,})expect(result.is_error).toBe(false)- expect(result.spillover_ref).toBe(`spillover://${TASK_ID}/read-2.json`)- const summary = JSON.parse(result.content) as SpilloverSummary- expect(summary.head).toContain(- `"byteRange":{"offset":${PAGE_BYTES},"length":${bytes.length - PAGE_BYTES}}`- )- expect(summary.head).toContain('"truncated":false')- expect(summary.tail).toContain(serializedText(fileText).slice(-100))+ expect(result.spillover_ref).toBeUndefined()+ const page = unwrap(result.content)+ expect(page.byteRange).toEqual({ offset: PAGE_BYTES, length: bytes.length - PAGE_BYTES })+ expect(page.truncated).toBe(false)+ expect(page.text).toBe(fileText.slice(PAGE_BYTES))+ expect(eventTypes()).toContain('tool:completed')+ expect(eventTypes()).not.toContain('spillover:persisted')})- it('returns a page under the threshold inline and writes nothing to disk', async () => {- const fileText = 'line of notes\n'.repeat(3000)- const attachment = attachedFile(Buffer.from(fileText))+ it('recovers the whole file by following byteRange and truncated through the loop', async () => {+ const fileText = 'line of notes\n'.repeat(3600)+ const bytes = Buffer.from(fileText)+ const attachment = attachedFile(bytes)+ const reader = readerFor(attachment)++ const pages: InlinePage[] = []+ let offset = 0+ do {+ const result = await run(reader, `read-${pages.length + 1}`, {+ attachmentId: ATTACHMENT_ID,+ offset,+ maxBytes: PAGE_BYTES,+ })+ expect(result.is_error).toBe(false)+ expect(result.spillover_ref).toBeUndefined()+ const page = unwrap(result.content)+ expect(page.byteRange.offset).toBe(offset)+ pages.push(page)+ offset = page.byteRange.offset + page.byteRange.length+ } while (pages[pages.length - 1]!.truncated)++ expect(pages.length).toBe(Math.ceil(bytes.length / PAGE_BYTES))+ expect(pages.map(page => page.text).join('')).toBe(fileText)+ expect(emitted.filter(event => event.type === 'tool:completed')).toHaveLength(pages.length)+ expect(eventTypes()).not.toContain('spillover:persisted')+ })++ it('control: an unbounded sanitized tool of the same size still spills through the same storage', async () => {+ const output = JSON.stringify({ text: 'line of notes\n'.repeat(1500) })- const result = await readPage(attachment, 'read-3', { maxBytes: 1024 })+ const result = await run(unboundedTool('file_read', output), 'control-1', {})expect(result.is_error).toBe(false)- expect(result.spillover_ref).toBeUndefined()- // Witness: the page itself reached the model inline.- expect(result.content.startsWith(WRAPPER_OPEN)).toBe(true)- expect(result.content.endsWith(WRAPPER_CLOSE)).toBe(true)- const body = JSON.parse(result.content.slice(WRAPPER_OPEN.length, -WRAPPER_CLOSE.length)) as {- text: string- truncated: boolean- }- expect(body.text).toBe(fileText.slice(0, 1024))- expect(body.truncated).toBe(true)- await expect(fs.access(path.join(workspace, 'spillover', TASK_ID))).rejects.toMatchObject({- code: 'ENOENT',- })+ expect(result.spillover_ref).toBe(`spillover://${TASK_ID}/control-1.json`)+ expect(eventTypes()).toContain('spillover:persisted')+ const blob = await storage.load(result.spillover_ref!)+ expect(blob?.content).toContain(output.slice(0, 200))})})diff --git a/mcp-host/src/core/orchestration/loopConfig.ts b/mcp-host/src/core/orchestration/loopConfig.tsindex 7c7c65748..7a88ebb8a 100644--- a/mcp-host/src/core/orchestration/loopConfig.ts+++ b/mcp-host/src/core/orchestration/loopConfig.ts@@ -115,10 +115,11 @@ export interface LoopConfig {/*** T1.5 — Tool-result spillover. When set, `executeSingleTool` calls- * `spilloverStorage.maybePersist(...)` on every non-error output that is- * not produced by `clerum__spillover_read`. Outputs over the threshold are- * persisted out-of-band and the `tool` message ships a `SpilloverSummary`- * in `content` plus the URI on the lateral `spillover_ref` field.+ * `spilloverStorage.maybePersist(...)` on every non-error output of a tool+ * that does not declare `spilloverExempt()` (`clerum__spillover_read` and+ * `clerum__attachment_read` do). Outputs over the threshold are persisted+ * out-of-band and the `tool` message ships a `SpilloverSummary` in+ * `content` plus the URI on the lateral `spillover_ref` field.** When undefined, `executeSingleTool` returns inline content as before* (1:1 with the pre-T1.5 behavior).diff --git a/mcp-host/src/core/orchestration/toolUseLoopSingleTool.ts b/mcp-host/src/core/orchestration/toolUseLoopSingleTool.tsindex 2dd4ebb98..76d80a7b3 100644--- a/mcp-host/src/core/orchestration/toolUseLoopSingleTool.ts+++ b/mcp-host/src/core/orchestration/toolUseLoopSingleTool.ts@@ -168,11 +168,15 @@ export async function executeSingleTool(})// T1.5 — Spillover. If the sanitized output exceeds the configured byte- // threshold (and the tool isn't itself `clerum__spillover_read` or an- // error), persist the blob out-of-band and replace `content` with a- // rich JSON summary. The lateral `spillover_ref` field carries the URI- // (P0-002 Opción D) so the resume path can resolve in O(1) without- // re-parsing the LLM-bound JSON body.+ // threshold (and is not an error), persist the blob out-of-band and+ // replace `content` with a rich JSON summary. The lateral `spillover_ref`+ // field carries the URI (P0-002 Opción D) so the resume path can resolve+ // in O(1) without re-parsing the LLM-bound JSON body.+ //+ // A tool whose output is already bounded by its own contract declares+ // `spilloverExempt()` (`clerum__spillover_read` reads back a blob that was+ // spilled once; `clerum__attachment_read` returns the page the caller+ // asked for) and is shipped inline whatever its size (#666, #678).//// `rawContent` keeps the original blob untouched so the progress reporter// (and the workflow read-only fallbacks) still see the real output.@@ -182,7 +186,7 @@ export async function executeSingleTool(config.spilloverStorage &&config.taskId &&!output.is_error &&- call.name !== 'clerum__spillover_read'+ tool.spilloverExempt?.() !== true) {try {const summary = await config.spilloverStorage.maybePersist({diff --git a/mcp-host/src/core/spillover/storage.ts b/mcp-host/src/core/spillover/storage.tsindex 4cd924027..9559d7649 100644--- a/mcp-host/src/core/spillover/storage.ts+++ b/mcp-host/src/core/spillover/storage.ts@@ -163,7 +163,10 @@ export class SpilloverStorage {* Excludes (plan §4.1):* - `isError === true` → never spill (errors are tiny and worth inlining).* - `toolName === 'clerum__spillover_read'` → never spill (the user asked- * for the data; persisting it again is recursion bait).+ * for the data; persisting it again is recursion bait). This is the+ * storage's own invariant for any caller; the tool loop decides by+ * `Tool.spilloverExempt()` before calling here, which is how+ * `clerum__attachment_read` pages stay inline too (#666, #678).*/async maybePersist(args: MaybePersistArgs): Promise<SpilloverSummary | null> {const byteSize = Buffer.byteLength(args.content, 'utf8')diff --git a/mcp-host/src/core/tools/__tests__/attachmentRead.test.ts b/mcp-host/src/core/tools/__tests__/attachmentRead.test.tsindex eb3bc9898..ef219fd95 100644--- a/mcp-host/src/core/tools/__tests__/attachmentRead.test.ts+++ b/mcp-host/src/core/tools/__tests__/attachmentRead.test.ts@@ -21,8 +21,7 @@ afterEach(() => {vi.mocked(decodeTextContent).mockClear()})-const READ_LIMIT = 262_144-const SPILLOVER_THRESHOLD = 8192+const READ_LIMIT = 65_536const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])function rawFile(id: string, filename: string, mimeType: string, bytes: Buffer) {@@ -50,11 +49,7 @@ function admitted(raw: unknown[]): Attachment[] {return result.attachments!}-function toolFor(- attachments: Attachment[],- limit = READ_LIMIT,- spilloverThresholdBytes: number | null = SPILLOVER_THRESHOLD-): AttachmentReadTool {+function toolFor(attachments: Attachment[], limit = READ_LIMIT): AttachmentReadTool {const message: IncomingMessage = {content: 'Analyze the attached file',channelType: 'rpc',@@ -65,7 +60,7 @@ function toolFor(hostRef: 'host-1',attachments,}- return new AttachmentReadTool(message, limit, spilloverThresholdBytes)+ return new AttachmentReadTool(message, limit)}async function read(tool: AttachmentReadTool, params: Record<string, unknown>) {@@ -201,7 +196,10 @@ describe('clerum__attachment_read', () => {truncated = body.truncated as booleancalls += 1}- expect(calls).toBe(2)+ // Pages cover the file; the boundary correction shortens a page by at most+ // one byte, so the count is pinned between the two page-size bounds.+ expect(calls).toBeGreaterThanOrEqual(Math.ceil(bytes.length / READ_LIMIT))+ expect(calls).toBeLessThanOrEqual(Math.ceil(bytes.length / (READ_LIMIT - 1)))// Witness: text came back, and none of it is a replacement character.expect(pages[0]!.length).toBeGreaterThan(0)expect(pages.join('')).toBe(original)@@ -255,18 +253,15 @@ describe('clerum__attachment_read', () => {])})- it('states the spillover threshold in its description when results can spill', () => {- const description = toolFor([], READ_LIMIT, SPILLOVER_THRESHOLD).description()- expect(description).toContain(- `A page whose result reaches the tool-output spillover threshold (${SPILLOVER_THRESHOLD} bytes) is returned as a spillover summary.`- )- expect(description).toContain('clerum__spillover_read')+ it('declares its output exempt from spillover: the caller bounds the page', () => {+ expect(toolFor([]).spilloverExempt?.()).toBe(true)})- it('does not mention spillover when this execution has no spillover storage', () => {- const description = toolFor([], READ_LIMIT, null).description()+ it('describes a page as returned whole and never mentions spillover', () => {+ const description = toolFor([]).description()// Witness: the description is the tool's full text.expect(description).toContain('Files with reader=text return UTF-8 text')+ expect(description).toContain('A page is returned whole')expect(description).not.toContain('spillover')})diff --git a/mcp-host/src/core/tools/__tests__/nativeToolRegistry.attachmentRead.test.ts b/mcp-host/src/core/tools/__tests__/nativeToolRegistry.attachmentRead.test.tsindex f76e92c19..a6fad4b06 100644--- a/mcp-host/src/core/tools/__tests__/nativeToolRegistry.attachmentRead.test.ts+++ b/mcp-host/src/core/tools/__tests__/nativeToolRegistry.attachmentRead.test.ts@@ -19,8 +19,7 @@ const config: NativeToolConfig = {httpAllowlist: [],envAllowlist: ['PATH'],memoryMaxSize: 1048576,- attachmentTextReadMaxBytes: 262_144,- toolSpilloverThresholdBytes: 8192,+ attachmentTextReadMaxBytes: 65_536,}function attachments(kind: 'file' | 'image'): Attachment[] {@@ -85,7 +84,7 @@ describe('NativeToolRegistry — clerum__attachment_read (#666)', () => {)expect(toolNames(registry)).toContain('clerum__attachment_read')expect(registry.get('clerum__attachment_read')!.parametersSchema()).toMatchObject({- properties: { maxBytes: { maximum: 262_144 } },+ properties: { maxBytes: { maximum: 65_536 } },})})@@ -117,19 +116,7 @@ describe('NativeToolRegistry — clerum__attachment_read (#666)', () => {).toThrow('NativeToolConfig.attachmentTextReadMaxBytes is required for file attachments')})- it('refuses to build without the spillover threshold when a file is attached', () => {- const { toolSpilloverThresholdBytes: _omitted, ...withoutThreshold } = config- // Control: the same config builds when no file is attached.- expect(- () => new NativeToolRegistry(withoutThreshold, 'conv-1', undefined, message())- ).not.toThrow()- expect(- () =>- new NativeToolRegistry(withoutThreshold, 'conv-1', undefined, message(attachments('file')))- ).toThrow('NativeToolConfig.toolSpilloverThresholdBytes is required for file attachments')- })-- it('states the spillover threshold only when the turn has spillover storage', () => {+ it('registers a spillover-exempt tool whether or not the turn has spillover storage', () => {const storage = new SpilloverStorage({workspacePath: '/tmp',thresholdBytes: 8192,@@ -147,13 +134,18 @@ describe('NativeToolRegistry — clerum__attachment_read (#666)', () => {undefined,storage)+ // Witness: this turn can spill (the read-back tool is present).expect(withSpillover.get('clerum__spillover_read')).not.toBeNull()- expect(withSpillover.get('clerum__attachment_read')!.description()).toContain(- 'spillover threshold (8192 bytes)'- )+ const spilling = withSpillover.get('clerum__attachment_read')!+ expect(spilling.spilloverExempt?.()).toBe(true)+ expect(spilling.description()).toContain('reader=text')+ expect(spilling.description()).not.toContain('spillover')+const inline = new NativeToolRegistry(config, 'conv-1', undefined, message(attachments('file')))- // Witness: the tool is registered and describes its text reader.- expect(inline.get('clerum__attachment_read')!.description()).toContain('reader=text')- expect(inline.get('clerum__attachment_read')!.description()).not.toContain('spillover')+ expect(inline.get('clerum__spillover_read')).toBeNull()+ const reader = inline.get('clerum__attachment_read')!+ expect(reader.spilloverExempt?.()).toBe(true)+ expect(reader.description()).toContain('reader=text')+ expect(reader.description()).not.toContain('spillover')})})diff --git a/mcp-host/src/core/tools/__tests__/spilloverRead.test.ts b/mcp-host/src/core/tools/__tests__/spilloverRead.test.tsindex 17f64b11c..fa4775442 100644--- a/mcp-host/src/core/tools/__tests__/spilloverRead.test.ts+++ b/mcp-host/src/core/tools/__tests__/spilloverRead.test.ts@@ -32,6 +32,10 @@ describe('SpilloverReadTool', () => {expect(tool.requiresApproval()).toBe(false)})+ it('declares its output exempt from spillover, so reading a blob back never re-persists it', () => {+ expect(tool.spilloverExempt?.()).toBe(true)+ })+it('returns the full blob content for a valid ref', async () => {const body = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'const summary = await storage.maybePersist({diff --git a/mcp-host/src/core/tools/attachmentRead.ts b/mcp-host/src/core/tools/attachmentRead.tsindex 8e3d93beb..1197aca07 100644--- a/mcp-host/src/core/tools/attachmentRead.ts+++ b/mcp-host/src/core/tools/attachmentRead.ts@@ -8,7 +8,10 @@** - `reader:'text'`: strict UTF-8 text, paged by byte `offset` and `maxBytes`* (at most `attachmentTextReadMaxBytes` per call). A page never splits a- * code point, so the text never carries U+FFFD.+ * code point, so the text never carries U+FFFD. The caller bounds the+ * page, so the tool is exempt from tool-output spillover and every page+ * reaches the model inline (#678); `attachmentTextReadMaxBytes` is sized+ * against the context budget for that reason.* - `reader:'none'`: a typed binary result; the bytes are never decoded.** The text-or-binary rule is the one `clerum__gfs_read` applies@@ -30,9 +33,9 @@ export type AttachmentReadErrorCode = 'attachment_not_found' | 'range_invalid'// digest). Name, class, size and reader are already on the file's// `attached_file` line, so they are not repeated on every page.//-// Key order is part of the contract: spillover keeps the first and last 400-// characters of the serialized result, so the paging fields come first and the-// text last. A spilled page's `head` then shows `byteRange` and `truncated`.+// Key order is part of the contract: the paging fields come first and the+// text last, so any reader that sees only the start of the serialized result+// (a preview, a truncated log line) still sees `byteRange` and `truncated`.export type AttachmentReadResult =| {attachmentId: string@@ -64,14 +67,10 @@ export class AttachmentReadTool implements Tool {/** Decoded bytes and the whole-file text check, per attachmentId. */private readonly decoded = new Map<string, { bytes: Buffer; isText: boolean }>()- /**- * @param spilloverThresholdBytes the tool-output spillover threshold, or- * null when this execution has no spillover storage (results stay inline).- */+ /** @param maxBytesPerCall the per-call ceiling and the default page. */constructor(private readonly sourceMessage: IncomingMessage,- private readonly maxBytesPerCall: number,- private readonly spilloverThresholdBytes: number | null+ private readonly maxBytesPerCall: number) {}name(): string {@@ -82,11 +81,7 @@ export class AttachmentReadTool implements Tool {return ('Read a file attached to the current message, by the attachmentId listed as attached_file in the turn context. ' +'Files with reader=text return UTF-8 text; read further pages with offset when truncated is true. ' +- (this.spilloverThresholdBytes === null- ? ''- : `A page whose result reaches the tool-output spillover threshold (${this.spilloverThresholdBytes} bytes) is returned as a spillover summary. ` +- 'Read it with clerum__spillover_read on its spillover_ref, or pass a smaller maxBytes. ' +- 'The result is a JSON object whose last field is text, so the head of a spillover summary shows byteRange and truncated. ') ++ `A page is returned whole, up to maxBytes (default ${this.maxBytesPerCall} bytes); pass a smaller maxBytes to read less at a time. ` +'Files with reader=none return a binary result without content. ' +'A reader=text file whose bytes fail the text check also returns a binary result; ' +'say the file cannot be read instead of guessing its content.'@@ -128,6 +123,12 @@ export class AttachmentReadTool implements Tool {return false}+ spilloverExempt(): boolean {+ // The caller bounds the page with `maxBytes`; replacing it with a+ // spillover summary would make the model ask for the same bytes twice.+ return true+ }+traceDescriptor(): ToolTraceDescriptor {return { kind: 'internal_tool', sourceRef: 'mcp-host' }}diff --git a/mcp-host/src/core/tools/nativeToolRegistry.ts b/mcp-host/src/core/tools/nativeToolRegistry.tsindex 368698bde..03af4ee12 100644--- a/mcp-host/src/core/tools/nativeToolRegistry.ts+++ b/mcp-host/src/core/tools/nativeToolRegistry.ts@@ -278,20 +278,10 @@ export class NativeToolRegistry implements ToolRegistry {'NativeToolConfig.attachmentTextReadMaxBytes is required for file attachments')}- const spilloverThresholdBytes = config.toolSpilloverThresholdBytes- if (spilloverThresholdBytes === undefined) {- throw new Error(- 'NativeToolConfig.toolSpilloverThresholdBytes is required for file attachments'- )- }- // The description names the threshold only where the loop can spill.- this.register(- new AttachmentReadTool(- sourceMessage,- maxBytes,- spilloverStorage ? spilloverThresholdBytes : null- )- )+ // The tool declares itself spillover-exempt: a page is bounded by+ // `maxBytes`, so the loop ships it inline whether or not this turn has+ // spillover storage (#678).+ this.register(new AttachmentReadTool(sourceMessage, maxBytes))}const envGetter = (key: string): string | undefined => {diff --git a/mcp-host/src/core/tools/spilloverRead.ts b/mcp-host/src/core/tools/spilloverRead.tsindex 0a2568992..ce02f6519 100644--- a/mcp-host/src/core/tools/spilloverRead.ts+++ b/mcp-host/src/core/tools/spilloverRead.ts@@ -7,8 +7,10 @@* this tool with `ref` (and optionally a `[start, end)` byte range) to fetch* the full content on demand.*- * Important: this tool itself NEVER spills its own output (excepción §4.1 of- * the plan). The check lives in `executeSingleTool` and is keyed by tool name.+ * Important: this tool itself NEVER spills its own output (exception §4.1 of+ * the plan). It declares `spilloverExempt()`, which `executeSingleTool`+ * honours; `SpilloverStorage.maybePersist` keeps a guard on the tool name as+ * its own recursion invariant.*/import { Tool } from '../interfaces'import { SpilloverStorage, clerumSpilloverReadsTotal } from '../spillover'@@ -64,6 +66,12 @@ export class SpilloverReadTool implements Tool {return false}+ spilloverExempt(): boolean {+ // The model asked for the bytes of a blob that was spilled once;+ // spilling them again would be recursion.+ return true+ }+async execute(params: Record<string, unknown>): Promise<ToolOutput> {const start = Date.now()const ref = typeof params.ref === 'string' ? (params.ref as string) : nulldiff --git a/mcp-host/src/server.ts b/mcp-host/src/server.tsindex a8420a6d2..c57759059 100644--- a/mcp-host/src/server.ts+++ b/mcp-host/src/server.ts@@ -140,19 +140,27 @@ export type {* (~21.3MiB base64) plus the 1MiB non-image share still fits. Every other* route keeps the 10mb ordinary JSON cap (see the parsers below).* - MAX_NON_IMAGE_BODY_BYTES bounds that same body MINUS credited image- * base64 (16MiB per image, at most 20 images / 16MiB total). Usual product- * target remains 5 / 9 / 14 MiB at 2048 px.- * - `kind:'file'` attachments are never credited: their base64 (4/3 of the- * decoded size) counts against MAX_NON_IMAGE_BODY_BYTES with the rest of- * the body. One file at the 3MiB CLERUM_ATTACHMENT_FILE_MAX_BYTES default- * (4MiB base64) fits; two do not, and the message gets this 413 before- * admission can answer FILE_ATTACHMENT_TOO_LARGE for either file.+ * base64 (16MiB per image, at most 20 images / 16MiB total) and MINUS+ * credited file base64. Usual product target remains 5 / 9 / 14 MiB at+ * 2048 px.+ * - `kind:'file'` attachments have their own quota (issue #678): a file with+ * the exact composer wire shape is credited up to 11MiB decoded each,+ * 20 files and 16MiB of base64 in total, and a qualifying file that breaks+ * the count or the total rejects the request. The text, the JSON envelope+ * and the non-base64 fields of each file entry stay in the 6MiB share, and+ * a file without the wire shape is charged there in full. The 11MiB+ * matches the CLERUM_ATTACHMENT_FILE_MAX_BYTES default, so admission can+ * still answer FILE_ATTACHMENT_TOO_LARGE for a lowered override.*/const MAX_CHAT_BODY_BYTES = 24 * 1024 * 1024const MAX_NON_IMAGE_BODY_BYTES = 6 * 1024 * 1024const MAX_CHAT_IMAGES = 20const MAX_IMAGE_DECODED_BYTES = 16 * 1024 * 1024const MAX_IMAGE_DECODED_BYTES_TOTAL = 16 * 1024 * 1024+const MAX_CHAT_FILES = 20+const MAX_FILE_DECODED_BYTES = 11 * 1024 * 1024+const MAX_FILE_BASE64_BYTES_TOTAL = 16 * 1024 * 1024+const SHA256_HEX_RE = /^[0-9a-f]{64}$/const BASE64_RE = /^[A-Za-z0-9+/]+={0,2}$/const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])const JPEG_SIGNATURE = Buffer.from([0xff, 0xd8, 0xff])@@ -246,10 +254,68 @@ function inspectChatImageBudget(body: unknown): {return { creditedBase64: credited, rejectImages: false }}+/**+ * Byte length of the base64 that counts against the file quota. Only a+ * `kind:'file'` attachment with the exact wire shape the composer produces+ * qualifies: `encoding: 'base64'`, a non-empty file name, a sha256 digest of+ * 64 lowercase hex characters, canonical non-empty base64 of at most 11MiB+ * decoded, within a 20-file / 16MiB-of-base64 total. A qualifying file that+ * would break the count or the total is fail-loud rather than charged as text.+ * Anything else is charged to the non-image budget, so a claim cannot be+ * smuggled through by mislabelling a payload. Mirror of rpc-proxy+ * `inspectChatFileBudget`; size, digest and class are verified at admission.+ */+function inspectChatFileBudget(body: unknown): {+ creditedBase64: number+ rejectFiles: boolean+} {+ if (!body || typeof body !== 'object' || Array.isArray(body)) {+ return { creditedBase64: 0, rejectFiles: false }+ }+ const attachments = (body as { attachments?: unknown }).attachments+ if (!Array.isArray(attachments)) return { creditedBase64: 0, rejectFiles: false }++ let credited = 0+ let counted = 0+ for (const attachment of attachments) {+ if (!attachment || typeof attachment !== 'object') continue+ const candidate = attachment as {+ kind?: unknown+ encoding?: unknown+ filename?: unknown+ digest?: unknown+ dataBase64?: unknown+ }+ if (candidate.kind !== 'file' || candidate.encoding !== 'base64') continue+ if (typeof candidate.filename !== 'string' || candidate.filename.length === 0) continue+ const digest = candidate.digest as { algorithm?: unknown; hex?: unknown } | null | undefined+ if (+ !digest ||+ typeof digest !== 'object' ||+ digest.algorithm !== 'sha256' ||+ typeof digest.hex !== 'string' ||+ !SHA256_HEX_RE.test(digest.hex)+ ) {+ continue+ }+ const dataBase64 = typeof candidate.dataBase64 === 'string' ? candidate.dataBase64 : ''+ const decoded = decodedBase64Bytes(dataBase64)+ if (decoded === null || decoded <= 0 || decoded > MAX_FILE_DECODED_BYTES) continue+ if (counted >= MAX_CHAT_FILES || credited + dataBase64.length > MAX_FILE_BASE64_BYTES_TOTAL) {+ return { creditedBase64: credited, rejectFiles: true }+ }+ credited += dataBase64.length+ counted += 1+ }+ return { creditedBase64: credited, rejectFiles: false }+}+function chatBodyExceedsNonImageBudget(rawBodyBytes: number, body: unknown): boolean {- const budget = inspectChatImageBudget(body)- if (budget.rejectImages) return true- return rawBodyBytes - budget.creditedBase64 > MAX_NON_IMAGE_BODY_BYTES+ const images = inspectChatImageBudget(body)+ if (images.rejectImages) return true+ const files = inspectChatFileBudget(body)+ if (files.rejectFiles) return true+ return rawBodyBytes - images.creditedBase64 - files.creditedBase64 > MAX_NON_IMAGE_BODY_BYTES}export class RPCServer {@@ -315,8 +381,8 @@ export class RPCServer {// Image and file attachments are sent as base64 in /v1/runtime/messages.// That route alone gets the 24 MiB ceiling; within it, only qualifying- // images are credited, and `kind:'file'` base64 is charged to the 6 MiB- // non-image budget like any other field. Every other Host route uses+ // images and files are credited, and every other field is charged to the+ // 6 MiB non-image budget. Every other Host route uses// the same 10mb ordinary JSON cap as rpc-proxy `jsonBody`, so a future// non-chat control body cannot 413 here and pass the proxy.const jsonParser = express.json({ limit: '10mb' })diff --git a/rpc-proxy/package-lock.json b/rpc-proxy/package-lock.jsonindex fa235616b..0796f6589 100644--- a/rpc-proxy/package-lock.json+++ b/rpc-proxy/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-rpc-proxy",- "version": "0.1.94",+ "version": "0.1.95","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-rpc-proxy",- "version": "0.1.94",+ "version": "0.1.95","dependencies": {"cors": "^2.8.5","express": "^4.21.2",diff --git a/rpc-proxy/package.json b/rpc-proxy/package.jsonindex cbaa8cf89..ef129fee1 100644--- a/rpc-proxy/package.json+++ b/rpc-proxy/package.json@@ -1,6 +1,6 @@{"name": "clerum-rpc-proxy",- "version": "0.1.94",+ "version": "0.1.95","description": "External-facing RPC proxy for tenant-scoped MCP access","main": "dist/main.js","engines": {diff --git a/rpc-proxy/src/__tests__/bodylimits.test.ts b/rpc-proxy/src/__tests__/bodylimits.test.tsindex 83c2fcd40..9efbd8843 100644--- a/rpc-proxy/src/__tests__/bodylimits.test.ts+++ b/rpc-proxy/src/__tests__/bodylimits.test.ts@@ -5,6 +5,8 @@* - `POST /api/v1/rpc/hosts/:hostRef/messages` carries the documented image* payloads (a 10MiB image, a 5MiB JPEG, 10MiB + 5MiB, and three 5MiB images) to the auth* boundary instead of being rejected as too large.+ * - Qualifying `kind:'file'` attachments have their own credited quota+ * (11MiB decoded per file, 16MiB of base64 in total, issue #678).* - The larger ceiling is NOT a general text allowance: non-image bytes stay* capped at 6MiB, and every other route keeps its 10mb parser.* - The sandbox-ui view proxy stays parser-free. A finished application/json@@ -364,37 +366,227 @@ describe('rpc-proxy chat message body budget', () => {expect(forwardedBody().attachments).toEqual(payload.attachments)})- it('rejects a file body 1KiB over the non-image budget with 413', async () => {+ it('charges a file body without a digest to the non-image budget', async () => {+ // A file without the composer's sha256 digest is never credited to the+ // file quota, so its base64 counts against the 6MiB share.+ const withoutDigest = (targetBytes: number) => {+ const payload = fileMessageOfBodySize(targetBytes)+ const { digest: _digest, ...attachment } = payload.attachments[0]!+ return { ...payload, attachments: [attachment] }+ }// Control: the same construction under the budget is forwarded.- expect((await postMessage(fileMessageOfBodySize(NON_IMAGE_BUDGET - KIB))).status).toBe(200)+ expect((await postMessage(withoutDigest(NON_IMAGE_BUDGET - KIB))).status).toBe(200)expect(serviceMock.forwardHostMessageToHost).toHaveBeenCalledTimes(1)vi.clearAllMocks()- const response = await postMessage(fileMessageOfBodySize(NON_IMAGE_BUDGET + KIB))+ const response = await postMessage(withoutDigest(NON_IMAGE_BUDGET + KIB))expect(response.status).toBe(413)expect(serviceMock.forwardHostMessageToHost).not.toHaveBeenCalled()})+ })- it('never credits PNG bytes sent as kind:file against the image budget', async () => {- const image = imageAttachment('a1', 7 * MIB)- const asImage = await postMessage({ content: 'look', attachments: [image] })- expect(asImage.status).toBe(200)+ describe('kind:file attachments have their own credited quota (issue #678)', () => {+ const FILE_MAX_BYTES = 11 * MIB+ const FILE_QUOTA_BASE64 = 16 * MIB+ const NON_IMAGE_BUDGET = 6 * MIB+ const KIB = 1024+ const fileBase64Cache = new Map<number, string>()++ /** Canonical base64 of `sizeBytes` bytes of ASCII text. */+ function textFileBase64(sizeBytes: number): string {+ return cachedBase64(fileBase64Cache, Buffer.alloc(sizeBytes, 0x61), sizeBytes)+ }++ function textFile(id: string, sizeBytes: number) {+ return {+ id,+ kind: 'file',+ mimeType: 'text/plain',+ detectedMediaType: 'text/plain',+ encoding: 'base64',+ dataBase64: textFileBase64(sizeBytes),+ filename: `${id}.txt`,+ sizeBytes,+ digest: { algorithm: 'sha256', hex: 'ab'.repeat(32) },+ }+ }++ /**+ * A message whose body minus the base64 of `attachments` is exactly+ * `shareBytes`: the bytes the 6MiB share is charged when every file is+ * credited.+ */+ function messageWithShare(attachments: Array<{ dataBase64: string }>, shareBytes: number) {+ const base64Bytes = attachments.reduce((total, item) => total + item.dataBase64.length, 0)+ const overhead = Buffer.byteLength(JSON.stringify({ content: '', attachments })) - base64Bytes+ const payload = { content: 'x'.repeat(shareBytes - overhead), attachments }+ expect(Buffer.byteLength(JSON.stringify(payload)) - base64Bytes).toBe(shareBytes)+ return payload+ }++ function forwardedAttachmentIds(): unknown[] {+ expect(serviceMock.forwardHostMessageToHost).toHaveBeenCalledTimes(1)+ const body = serviceMock.forwardHostMessageToHost.mock.calls[0]![1] as {+ attachments?: Array<{ id: unknown }>+ }+ return (body.attachments ?? []).map(item => item.id)+ }++ it('carries an 11MiB file beside a text share 1KiB under 6MiB', async () => {+ const payload = messageWithShare([textFile('f1', FILE_MAX_BYTES)], NON_IMAGE_BUDGET - KIB)+ // The whole body is far past the 6MiB share: only the file credit lets it through.+ expect(Buffer.byteLength(JSON.stringify(payload))).toBeGreaterThan(20 * MIB)+ const response = await postMessage(payload)+ expect(response.status).toBe(200)+ expect(forwardedAttachmentIds()).toEqual(['f1'])+ })++ it('rejects an 11MiB file when the text share is 1KiB over 6MiB', async () => {+ const file = textFile('f1', FILE_MAX_BYTES)+ expect((await postMessage(messageWithShare([file], NON_IMAGE_BUDGET - KIB))).status).toBe(200)+ expect(serviceMock.forwardHostMessageToHost).toHaveBeenCalledTimes(1)+ vi.clearAllMocks()+ const response = await postMessage(messageWithShare([file], NON_IMAGE_BUDGET + KIB))+ expect(response.status).toBe(413)+ expect(serviceMock.forwardHostMessageToHost).not.toHaveBeenCalled()+ })++ it('decides the 11MiB limit by decoded bytes, not by base64 length', async () => {+ const atLimit = textFile('f1', FILE_MAX_BYTES)+ const overLimit = textFile('f1', FILE_MAX_BYTES + 1)+ // Both encode to the same number of characters; only the padding differs.+ expect(overLimit.dataBase64.length).toBe(atLimit.dataBase64.length)+ expect((await postMessage(messageWithShare([atLimit], KIB))).status).toBe(200)+ expect(serviceMock.forwardHostMessageToHost).toHaveBeenCalledTimes(1)+ vi.clearAllMocks()+ const response = await postMessage(messageWithShare([overLimit], KIB))+ expect(response.status).toBe(413)+ expect(serviceMock.forwardHostMessageToHost).not.toHaveBeenCalled()+ })++ it('does not credit file base64 whose padding carries non-zero unused bits', async () => {+ const canonical = textFile('f1', FILE_MAX_BYTES)+ const nonCanonical = {+ ...canonical,+ dataBase64: withNonCanonicalTailBits(canonical.dataBase64),+ }+ expect((await postMessage(messageWithShare([canonical], KIB))).status).toBe(200)+ expect(serviceMock.forwardHostMessageToHost).toHaveBeenCalledTimes(1)+ vi.clearAllMocks()+ const response = await postMessage(messageWithShare([nonCanonical], KIB))+ expect(response.status).toBe(413)+ expect(serviceMock.forwardHostMessageToHost).not.toHaveBeenCalled()+ })++ it.each([+ { label: 'no digest', mutate: ({ digest: _d, ...rest }: Record<string, unknown>) => rest },+ {+ label: 'a sha1 digest',+ mutate: (item: Record<string, unknown>) => ({+ ...item,+ digest: { algorithm: 'sha1', hex: 'ab'.repeat(32) },+ }),+ },+ {+ label: 'an uppercase digest',+ mutate: (item: Record<string, unknown>) => ({+ ...item,+ digest: { algorithm: 'sha256', hex: 'AB'.repeat(32) },+ }),+ },+ {+ label: 'a raw encoding',+ mutate: (item: Record<string, unknown>) => ({ ...item, encoding: 'raw' }),+ },+ {+ label: 'an empty file name',+ mutate: (item: Record<string, unknown>) => ({ ...item, filename: '' }),+ },+ {+ label: 'no file name',+ mutate: ({ filename: _f, ...rest }: Record<string, unknown>) => rest,+ },+ ])('charges a 5MiB file with $label to the non-image budget', async ({ mutate }) => {+ // 5MiB encodes to about 6.7MiB: credited it fits, charged as text it does not.+ const complete = textFile('f1', 5 * MIB)+ expect((await postMessage(messageWithShare([complete], KIB))).status).toBe(200)expect(serviceMock.forwardHostMessageToHost).toHaveBeenCalledTimes(1)vi.clearAllMocks()- // Same MIME type and bytes as the image: only `kind` differs.- const asFile = await postMessage({+ const response = await postMessage({ content: 'look', attachments: [mutate(complete)] })+ expect(response.status).toBe(413)+ expect(serviceMock.forwardHostMessageToHost).not.toHaveBeenCalled()+ })++ it('carries files that sit exactly on the 16MiB base64 quota and rejects one byte past it', async () => {+ const large = textFile('f1', FILE_MAX_BYTES)+ const fitting = textFile('f2', MIB - 1)+ const overflowing = textFile('f2', MIB)+ expect(large.dataBase64.length + fitting.dataBase64.length).toBe(FILE_QUOTA_BASE64)+ expect(large.dataBase64.length + overflowing.dataBase64.length).toBeGreaterThan(+ FILE_QUOTA_BASE64+ )+ const ok = await postMessage(messageWithShare([large, fitting], KIB))+ expect(ok.status).toBe(200)+ expect(forwardedAttachmentIds()).toEqual(['f1', 'f2'])+ vi.clearAllMocks()+ const response = await postMessage(messageWithShare([large, overflowing], KIB))+ expect(response.status).toBe(413)+ expect(serviceMock.forwardHostMessageToHost).not.toHaveBeenCalled()+ })++ it('credits PNG bytes sent as kind:file to the file quota, up to 11MiB', async () => {+ const pngAsFile = (sizeBytes: number) => ({+ ...textFile('f1', 1),+ dataBase64: pngBase64(sizeBytes),+ mimeType: 'image/png',+ detectedMediaType: 'image/png',+ filename: 'photo.png',+ sizeBytes,+ })+ const small = await postMessage({ content: 'look', attachments: [pngAsFile(7 * MIB)] })+ expect(small.status).toBe(200)+ expect(forwardedAttachmentIds()).toEqual(['f1'])+ vi.clearAllMocks()+ // The same 12MiB bytes are credited as an image (16MiB limit)…+ const asImage = await postMessage({content: 'look',- attachments: [- {- ...fileAttachment(image.dataBase64),- mimeType: 'image/png',- detectedMediaType: 'image/png',- filename: 'photo.png',- },- ],+ attachments: [imageAttachment('a1', 12 * MIB)],})+ expect(asImage.status).toBe(200)+ expect(serviceMock.forwardHostMessageToHost).toHaveBeenCalledTimes(1)+ vi.clearAllMocks()+ // …but not as a file, whose limit is 11MiB.+ const asFile = await postMessage({ content: 'look', attachments: [pngAsFile(12 * MIB)] })expect(asFile.status).toBe(413)expect(serviceMock.forwardHostMessageToHost).not.toHaveBeenCalled()})++ it('carries an 11MiB file beside a 5MiB image and rejects the pair past 24MiB', async () => {+ const file = textFile('f1', FILE_MAX_BYTES)+ const fits = { content: 'look', attachments: [file, imageAttachment('a1', 5 * MIB)] }+ expect(Buffer.byteLength(JSON.stringify(fits))).toBeLessThan(24 * MIB)+ expect((await postMessage(fits)).status).toBe(200)+ expect(forwardedAttachmentIds()).toEqual(['f1', 'a1'])+ vi.clearAllMocks()+ const tooBig = { content: 'look', attachments: [file, imageAttachment('a1', 8 * MIB)] }+ expect(Buffer.byteLength(JSON.stringify(tooBig))).toBeGreaterThan(24 * MIB)+ const response = await postMessage(tooBig)+ expect(response.status).toBe(413)+ expect(serviceMock.forwardHostMessageToHost).not.toHaveBeenCalled()+ })++ it('credits twenty files and rejects a twenty-first instead of charging it as text', async () => {+ const files = (count: number) =>+ Array.from({ length: count }, (_, index) => textFile(`f${index + 1}`, KIB))+ const twenty = await postMessage({ content: 'look', attachments: files(20) })+ expect(twenty.status).toBe(200)+ expect(forwardedAttachmentIds()).toHaveLength(20)+ vi.clearAllMocks()+ const body = { content: 'look', attachments: files(21) }+ expect(Buffer.byteLength(JSON.stringify(body))).toBeLessThan(NON_IMAGE_BUDGET)+ const response = await postMessage(body)+ expect(response.status).toBe(413)+ expect(serviceMock.forwardHostMessageToHost).not.toHaveBeenCalled()+ })})it('rejects a body past the 24MiB ceiling', async () => {diff --git a/rpc-proxy/src/middleware/chatJsonBody.ts b/rpc-proxy/src/middleware/chatJsonBody.tsindex 4feffd74c..2c9625cdb 100644--- a/rpc-proxy/src/middleware/chatJsonBody.ts+++ b/rpc-proxy/src/middleware/chatJsonBody.ts@@ -1,7 +1,7 @@import express, { type NextFunction, type Request, type Response } from 'express'/**- * Body budgets for chat payloads carrying base64 image attachments.+ * Body budgets for chat payloads carrying base64 image and file attachments.** Usual product target is 5MiB / 9MiB / 14MiB at 2048 px. Hard hop credit is* 16MiB per image and 16MiB total so a poorly compressed 2048 PNG may exceed@@ -13,8 +13,13 @@ import express, { type NextFunction, type Request, type Response } from 'express* still fits. The 6MiB non-image share is a separate ceiling, not added* on top of that image.* - MAX_NON_IMAGE_BODY_BYTES bounds the same body MINUS credited image- * base64. Without that subtraction the attachment budget would become a- * general 24MiB text budget.+ * base64 and MINUS credited file base64. Without those subtractions the+ * attachment budgets would become a general 24MiB text budget.+ *+ * `kind:'file'` has its own quota (issue #678): at most 11MiB decoded per file+ * and 16MiB of base64 in total, credited exactly like images. The text, the+ * JSON envelope and the non-base64 fields of each file entry stay in the 6MiB+ * share, so a text-only message keeps its 6MiB ceiling.** Mount `chatJsonBody` on `POST /rpc/hosts/:hostRef/messages` right after* authentication so unauthenticated callers never trigger this parser.@@ -24,6 +29,10 @@ const MAX_NON_IMAGE_BODY_BYTES = 6 * 1024 * 1024const MAX_CHAT_IMAGES = 20const MAX_IMAGE_DECODED_BYTES = 16 * 1024 * 1024const MAX_IMAGE_DECODED_BYTES_TOTAL = 16 * 1024 * 1024+const MAX_CHAT_FILES = 20+const MAX_FILE_DECODED_BYTES = 11 * 1024 * 1024+const MAX_FILE_BASE64_BYTES_TOTAL = 16 * 1024 * 1024+const SHA256_HEX_RE = /^[0-9a-f]{64}$/const BASE64_RE = /^[A-Za-z0-9+/]+={0,2}$/const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])const JPEG_SIGNATURE = Buffer.from([0xff, 0xd8, 0xff])@@ -119,10 +128,68 @@ function inspectChatImageBudget(body: unknown): {return { creditedBase64: credited, rejectImages: false }}+/**+ * Byte length of the base64 that counts against the file quota. Only a+ * `kind:'file'` attachment with the exact wire shape the composer produces+ * qualifies: `encoding: 'base64'`, a non-empty file name, a sha256 digest of+ * 64 lowercase hex characters, canonical non-empty base64 of at most 11MiB+ * decoded, within a 20-file / 16MiB-of-base64 total. A qualifying file that+ * would break the count or the total is fail-loud rather than charged as text.+ * Anything else is charged to the non-image budget, so a claim cannot be+ * smuggled through by mislabelling a payload. The proxy never hashes: the Host+ * verifies size, digest and class at admission.+ */+function inspectChatFileBudget(body: unknown): {+ creditedBase64: number+ rejectFiles: boolean+} {+ if (!body || typeof body !== 'object' || Array.isArray(body)) {+ return { creditedBase64: 0, rejectFiles: false }+ }+ const attachments = (body as { attachments?: unknown }).attachments+ if (!Array.isArray(attachments)) return { creditedBase64: 0, rejectFiles: false }++ let credited = 0+ let counted = 0+ for (const attachment of attachments) {+ if (!attachment || typeof attachment !== 'object') continue+ const candidate = attachment as {+ kind?: unknown+ encoding?: unknown+ filename?: unknown+ digest?: unknown+ dataBase64?: unknown+ }+ if (candidate.kind !== 'file' || candidate.encoding !== 'base64') continue+ if (typeof candidate.filename !== 'string' || candidate.filename.length === 0) continue+ const digest = candidate.digest as { algorithm?: unknown; hex?: unknown } | null | undefined+ if (+ !digest ||+ typeof digest !== 'object' ||+ digest.algorithm !== 'sha256' ||+ typeof digest.hex !== 'string' ||+ !SHA256_HEX_RE.test(digest.hex)+ ) {+ continue+ }+ const dataBase64 = typeof candidate.dataBase64 === 'string' ? candidate.dataBase64 : ''+ const decoded = decodedBase64Bytes(dataBase64)+ if (decoded === null || decoded <= 0 || decoded > MAX_FILE_DECODED_BYTES) continue+ if (counted >= MAX_CHAT_FILES || credited + dataBase64.length > MAX_FILE_BASE64_BYTES_TOTAL) {+ return { creditedBase64: credited, rejectFiles: true }+ }+ credited += dataBase64.length+ counted += 1+ }+ return { creditedBase64: credited, rejectFiles: false }+}+function chatBodyExceedsNonImageBudget(rawBodyBytes: number, body: unknown): boolean {- const budget = inspectChatImageBudget(body)- if (budget.rejectImages) return true- return rawBodyBytes - budget.creditedBase64 > MAX_NON_IMAGE_BODY_BYTES+ const images = inspectChatImageBudget(body)+ if (images.rejectImages) return true+ const files = inspectChatFileBudget(body)+ if (files.rejectFiles) return true+ return rawBodyBytes - images.creditedBase64 - files.creditedBase64 > MAX_NON_IMAGE_BODY_BYTES}const chatJsonParser = express.json({diff --git a/tests/e2e/fixtures/image-capabilities/README.md b/tests/e2e/fixtures/image-capabilities/README.mdindex f74ec51f1..b3a207519 100644--- a/tests/e2e/fixtures/image-capabilities/README.md+++ b/tests/e2e/fixtures/image-capabilities/README.md@@ -29,8 +29,10 @@ tool result arrives, it replies `DOCUMENT_FIXTURE_SHA256:` plus the first 16 hexcharacters of the SHA-256 of the text in that result. The prompt alone can neverproduce that answer.-The ledger records `document-read-requested` (no digest yet) and-`document-answer` (with `documentSha256`, never the text). Malformed, non-text+The ledger records `document-read-requested` (no digest yet, with+`documentByteLength` taken from the `bytes=` field the Host wrote on the+`attached_file` line) and `document-answer` (with `documentSha256`, never the+text). An `attached_file` line without a positive `bytes=`, malformed, non-textor repeated tool results and streamed document turns are refused and counted in`documentFailures`. Image rows keep their previous shape.diff --git a/tests/e2e/fixtures/image-capabilities/provider.mjs b/tests/e2e/fixtures/image-capabilities/provider.mjsindex c25139bde..842135527 100644--- a/tests/e2e/fixtures/image-capabilities/provider.mjs+++ b/tests/e2e/fixtures/image-capabilities/provider.mjs@@ -350,7 +350,17 @@ const DOCUMENT_ANSWER_PREFIX = 'DOCUMENT_FIXTURE_SHA256:'const DOCUMENT_ANSWER_DIGEST_CHARS = 16/** The `attached_file` line the Host writes into the turn-context block. */-const ATTACHED_FILE_LINE = /^attached_file: id="([^"\n]+)"/m+const ATTACHED_FILE_LINE = /^attached_file: id="([^"\n]+)"[^\n]*$/m++/**+ * The trailing fields of that line (`turnContext.ts`): the byte length the Host+ * verified, then the reader. Anchored to the end of the line, so a file name+ * that contains the same text cannot supply the value.+ */+const ATTACHED_FILE_BYTES = / bytes=(\S*) reader=\S+$/++/** A positive decimal integer without leading zeros. */+const POSITIVE_DECIMAL = /^[1-9][0-9]*$//** The wrapper the Host puts around a tool result (`BasicSafety.wrapForLlm`). */const ATTACHMENT_TOOL_OUTPUT = new RegExp(@@ -373,12 +383,25 @@ function lastUserIndex(messages) {return -1}+/** The byte length the Host listed for the attached file; anything else is refused. */+function attachedFileByteLength(line) {+ const field = ATTACHED_FILE_BYTES.exec(line)+ const value = field?.[1]+ if (value === undefined || !POSITIVE_DECIMAL.test(value) || !Number.isSafeInteger(Number(value)))+ throw new FixtureDocumentError(+ 'document-byte-length-malformed',+ 'the attached_file line does not carry a positive bytes= value'+ )+ return Number(value)+}+/*** Classifies the request as one of the two turns of an attachment read.** - `null`: not a document turn (no `attached_file` line, or the read tool is not offered).- * - `{ stage: 'read', attachmentId }`: the user message lists a readable file and no tool- * result follows it yet, so the model has to ask for the text.+ * - `{ stage: 'read', attachmentId, byteLength }`: the user message lists a readable file+ * and no tool result follows it yet, so the model has to ask for the text. `byteLength`+ * is the size the Host listed for the file.* - `{ stage: 'answer', text }`: a `role:'tool'` message after the last user message carries* the wrapped tool result, so the model can answer from what was delivered.*@@ -399,7 +422,12 @@ function classifyDocumentTurn(body) {const toolMessages = body.messages.slice(userIndex + 1).filter(message => message?.role === 'tool' && typeof message.content === 'string')- if (toolMessages.length === 0) return { stage: 'read', attachmentId: attached[1] }+ if (toolMessages.length === 0)+ return {+ stage: 'read',+ attachmentId: attached[1],+ byteLength: attachedFileByteLength(attached[0]),+ }if (toolMessages.length > 1)throw new FixtureDocumentError('document-tool-result-count',@@ -689,14 +717,14 @@ export function createImageFixtureFetch(* request was refused before its body was parsed, and `imageSha256` is null* whenever the attempt carried no usable image.*/- const recordCall = (model, imageSha256, responseKind, documentSha256) => {- // Only document rows carry `documentSha256`, so the image rows keep the exact- // shape they always had.- state.attempts.push(+ const recordCall = (model, imageSha256, responseKind, documentSha256, documentByteLength) => {+ // Only document rows carry `documentSha256`, and only the read row carries+ // `documentByteLength`, so the image rows keep the exact shape they always had.+ const row =documentSha256 === undefined? { model, imageSha256, responseKind }: { model, imageSha256, responseKind, documentSha256 }- )+ state.attempts.push(documentByteLength === undefined ? row : { ...row, documentByteLength })}const refuse = (model, reason, { status = 400, code = reason, imageSha256 = null } = {}) => {state.counters.rejectedAttempts += 1@@ -800,7 +828,7 @@ export function createImageFixtureFetch(state.counters.documentReadRequests += 1sequence += 1const completionId = `${COMPLETION_ID_PREFIX}${runId.slice(-12)}-${sequence}`- recordCall(model, null, 'document-read-requested', null)+ recordCall(model, null, 'document-read-requested', null, documentTurn.byteLength)publish()return jsonResponse(toolCallCompletionBody(completionId, model, ATTACHMENT_READ_TOOL, {diff --git a/tests/e2e/fixtures/image-capabilities/provider.test.mjs b/tests/e2e/fixtures/image-capabilities/provider.test.mjsindex 8b1fb4f15..5e74b3c20 100644--- a/tests/e2e/fixtures/image-capabilities/provider.test.mjs+++ b/tests/e2e/fixtures/image-capabilities/provider.test.mjs@@ -717,12 +717,15 @@ const readToolDefinition = {},}-function documentUserMessage(text = 'Summarize the attached file.') {+function documentUserMessage(+ text = 'Summarize the attached file.',+ { bytesField = 'bytes=34' } = {}+) {return {role: 'user',content:'<turn-context>\ndate: 2026-09-29\n' +- `attached_file: id="${ATTACHMENT_ID}" name="notes.txt" class=text bytes=34 reader=text\n` ++ `attached_file: id="${ATTACHMENT_ID}" name="notes.txt" class=text ${bytesField} reader=text\n` +"If the user's request refers to an attached file, read it with clerum__attachment_read before answering.\n" +`</turn-context>\n\n${text}`,}@@ -784,10 +787,65 @@ test('document turn 1: asks for the text with a tool call and carries no file coimageSha256: null,responseKind: 'document-read-requested',documentSha256: null,+ documentByteLength: Buffer.byteLength(DOCUMENT_TEXT),},])})+test('document turn 1: the read row records the byte length the Host listed, not a constant', async () => {+ const lengths = []+ for (const bytes of [34, 6_291_456]) {+ const h = harness()+ const response = await call(+ h,+ chatBody(VISUAL_MODEL, [documentUserMessage(undefined, { bytesField: `bytes=${bytes}` })], {+ tools: [readToolDefinition],+ })+ )+ assert.equal(response.status, 200)+ const [row] = h.getEvidence().attempts+ assert.equal(row.responseKind, 'document-read-requested')+ lengths.push(row.documentByteLength)+ }+ assert.deepEqual(lengths, [34, 6_291_456])+})++test('document turn 1: an attached_file line without a usable bytes= is refused, not read', async () => {+ // Liveness witness: the same message with a well-formed field is read.+ const twin = harness()+ const twinResponse = await call(+ twin,+ chatBody(VISUAL_MODEL, [documentUserMessage()], { tools: [readToolDefinition] })+ )+ assert.equal(twinResponse.status, 200)+ assert.equal(twin.getEvidence().counters.documentReadRequests, 1)++ for (const bytesField of [+ 'size=34',+ 'bytes=',+ 'bytes=abc',+ 'bytes=34x',+ 'bytes=1.5',+ 'bytes=-1',+ 'bytes=0',+ 'bytes=034',+ ]) {+ const h = harness()+ const response = await call(+ h,+ chatBody(VISUAL_MODEL, [documentUserMessage(undefined, { bytesField })], {+ tools: [readToolDefinition],+ })+ )+ assert.equal(response.status, 400, bytesField)+ const evidence = h.getEvidence()+ assert.equal(evidence.counters.documentFailures, 1, bytesField)+ assert.equal(evidence.counters.documentReadRequests, 0, bytesField)+ assert.equal(evidence.attempts[0].responseKind, 'rejected', bytesField)+ assert.equal((await response.json()).error.code, 'document-byte-length-malformed', bytesField)+ }+})+test('document turn 2: the answer is a digest of the delivered text and the ledger records it', async () => {const h = harness()diff --git a/tests/e2e/fixtures/image-capabilities/sdk.test.mjs b/tests/e2e/fixtures/image-capabilities/sdk.test.mjsindex ff212de9d..d396a40fa 100644--- a/tests/e2e/fixtures/image-capabilities/sdk.test.mjs+++ b/tests/e2e/fixtures/image-capabilities/sdk.test.mjs@@ -143,6 +143,7 @@ test('the production ZAI serializer and pinned SDK complete an attachment read aimageSha256: null,responseKind: 'document-read-requested',documentSha256: null,+ documentByteLength: Buffer.byteLength(documentText),},{model: 'glm-5.3-flash',diff --git a/tests/e2e/fixtures/package-lock.json b/tests/e2e/fixtures/package-lock.jsonindex 2e21df64b..8e11b8b25 100644--- a/tests/e2e/fixtures/package-lock.json+++ b/tests/e2e/fixtures/package-lock.json@@ -1,12 +1,12 @@{"name": "@clerum/e2e-test-fixtures",- "version": "1.0.101",+ "version": "1.0.102","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "@clerum/e2e-test-fixtures",- "version": "1.0.101",+ "version": "1.0.102","dependencies": {"@kubernetes/client-node": "^1.0.0"},diff --git a/tests/e2e/fixtures/package.json b/tests/e2e/fixtures/package.jsonindex 0523a0d75..84138e7b7 100644--- a/tests/e2e/fixtures/package.json+++ b/tests/e2e/fixtures/package.json@@ -1,6 +1,6 @@{"name": "@clerum/e2e-test-fixtures",- "version": "1.0.101",+ "version": "1.0.102","description": "E2E test fixtures and utilities for Clerum testing","type": "module","main": "index.ts",diff --git a/tests/e2e/integration/chat-body-budget-parity.test.ts b/tests/e2e/integration/chat-body-budget-parity.test.tsnew file mode 100644index 000000000..07686e836--- /dev/null+++ b/tests/e2e/integration/chat-body-budget-parity.test.ts@@ -0,0 +1,147 @@+/**+ * Parity gate for the chat request body budget (#678).+ *+ * rpc-proxy and mcp-host each parse the chat body with their own copy of the+ * budget (no shared package exists), and the Desktop composer mirrors the same+ * numbers to refuse an attachment before it is sent. A drift between any two+ * of them either lets the composer build a request a server rejects, or lets+ * one hop accept what the next refuses. This suite reads the sources and fails+ * when a limit or a qualification predicate differs.+ *+ * Every lookup must match exactly once: a renamed or duplicated constant fails+ * here instead of turning a comparison into one between two `undefined`s.+ */+import { describe, expect, it } from 'vitest'+import { readFileSync } from 'node:fs'+import { dirname, join } from 'node:path'+import { fileURLToPath } from 'node:url'++const here = dirname(fileURLToPath(import.meta.url))+const repoRoot = join(here, '../../..')++const MIB = 1024 * 1024++const sources = {+ rpcProxy: readFileSync(join(repoRoot, 'rpc-proxy/src/middleware/chatJsonBody.ts'), 'utf8'),+ mcpHost: readFileSync(join(repoRoot, 'mcp-host/src/server.ts'), 'utf8'),+ composer: readFileSync(join(repoRoot, 'desktop-app/ui/src/constants/attachments.ts'), 'utf8'),+ hostConfig: readFileSync(join(repoRoot, 'mcp-host/src/config.ts'), 'utf8'),+}++function soleMatch(source: string, pattern: RegExp, label: string): RegExpMatchArray {+ const flags = pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`+ const matches = [...source.matchAll(new RegExp(pattern.source, flags))]+ expect(matches.length, `${label} must appear exactly once`).toBe(1)+ return matches[0]+}++/** Value of `const NAME = 16 * 1024 * 1024` (or a plain integer literal). */+function constantValue(source: string, name: string, label: string): number {+ const [, expression] = soleMatch(+ source,+ new RegExp(`^(?:export )?const ${name} = ([0-9_]+(?: \\* [0-9_]+)*)$`, 'm'),+ `${label} ${name}`+ )+ return expression+ .split(' * ')+ .map(factor => Number(factor.replaceAll('_', '')))+ .reduce((product, factor) => product * factor, 1)+}++/** Source text of a top-level `function name(...) { ... }`, closed by a column-0 `}`. */+function functionSource(source: string, name: string, label: string): string {+ return soleMatch(+ source,+ new RegExp(`^function ${name}\\([\\s\\S]*?^\\}$`, 'm'),+ `${label} ${name}`+ )[0]+}++const SERVER_LIMITS: ReadonlyArray<readonly [string, number]> = [+ ['MAX_CHAT_BODY_BYTES', 24 * MIB],+ ['MAX_NON_IMAGE_BODY_BYTES', 6 * MIB],+ ['MAX_CHAT_IMAGES', 20],+ ['MAX_IMAGE_DECODED_BYTES', 16 * MIB],+ ['MAX_IMAGE_DECODED_BYTES_TOTAL', 16 * MIB],+ ['MAX_CHAT_FILES', 20],+ ['MAX_FILE_DECODED_BYTES', 11 * MIB],+ ['MAX_FILE_BASE64_BYTES_TOTAL', 16 * MIB],+]++const BUDGET_FUNCTIONS = [+ 'decodedBase64Bytes',+ 'inspectChatImageBudget',+ 'inspectChatFileBudget',+ 'chatBodyExceedsNonImageBudget',+] as const++describe('chat body budget parity across rpc-proxy, mcp-host and the composer (#678)', () => {+ it.each(SERVER_LIMITS)('both parsers declare %s with the same value', (name, expected) => {+ expect(constantValue(sources.rpcProxy, name, 'rpc-proxy')).toBe(expected)+ expect(constantValue(sources.mcpHost, name, 'mcp-host')).toBe(expected)+ })++ it('both parsers require the same lowercase sha256 hex digest', () => {+ const pattern = /^const SHA256_HEX_RE = (\/.+\/)$/m+ const rpcProxy = soleMatch(sources.rpcProxy, pattern, 'rpc-proxy SHA256_HEX_RE')[1]+ const mcpHost = soleMatch(sources.mcpHost, pattern, 'mcp-host SHA256_HEX_RE')[1]+ expect(rpcProxy).toBe('/^[0-9a-f]{64}$/')+ expect(mcpHost).toBe(rpcProxy)+ })++ it.each(BUDGET_FUNCTIONS)('both parsers implement %s identically', name => {+ const rpcProxy = functionSource(sources.rpcProxy, name, 'rpc-proxy')+ const mcpHost = functionSource(sources.mcpHost, name, 'mcp-host')+ // Witness: the extracted text is the function, not an empty or truncated match.+ expect(rpcProxy.split('\n').length).toBeGreaterThan(3)+ expect(mcpHost).toBe(rpcProxy)+ })++ it('credits a file by its decoded size, bounded by the per-file and total quotas', () => {+ const inspect = functionSource(sources.rpcProxy, 'inspectChatFileBudget', 'rpc-proxy')+ expect(inspect).toContain('decoded > MAX_FILE_DECODED_BYTES')+ expect(inspect).toContain('credited + dataBase64.length > MAX_FILE_BASE64_BYTES_TOTAL')+ expect(inspect).toContain('counted >= MAX_CHAT_FILES')+ expect(inspect).toContain('SHA256_HEX_RE.test(digest.hex)')+ const exceeds = functionSource(sources.rpcProxy, 'chatBodyExceedsNonImageBudget', 'rpc-proxy')+ expect(exceeds).toContain(+ 'rawBodyBytes - images.creditedBase64 - files.creditedBase64 > MAX_NON_IMAGE_BODY_BYTES'+ )+ })++ it('the composer mirrors the server limits', () => {+ const composer: ReadonlyArray<readonly [string, number]> = [+ [+ 'COMPOSER_MAX_REQUEST_BODY_BYTES',+ constantValue(sources.rpcProxy, 'MAX_CHAT_BODY_BYTES', 'rpc-proxy'),+ ],+ [+ 'COMPOSER_MAX_NON_IMAGE_BODY_BYTES',+ constantValue(sources.rpcProxy, 'MAX_NON_IMAGE_BODY_BYTES', 'rpc-proxy'),+ ],+ [+ 'COMPOSER_MAX_FILE_BYTES',+ constantValue(sources.rpcProxy, 'MAX_FILE_DECODED_BYTES', 'rpc-proxy'),+ ],+ [+ 'COMPOSER_MAX_TOTAL_FILE_BASE64_BYTES',+ constantValue(sources.rpcProxy, 'MAX_FILE_BASE64_BYTES_TOTAL', 'rpc-proxy'),+ ],+ ['COMPOSER_MAX_ATTACHMENTS', constantValue(sources.rpcProxy, 'MAX_CHAT_FILES', 'rpc-proxy')],+ ]+ for (const [name, serverValue] of composer) {+ expect(constantValue(sources.composer, name, 'composer'), name).toBe(serverValue)+ }+ })++ it('the Host admission default equals the per-file credit ceiling', () => {+ const [, literal] = soleMatch(+ sources.hostConfig,+ /getExecutionLimit\('CLERUM_ATTACHMENT_FILE_MAX_BYTES', ([0-9_]+)\)/,+ 'mcp-host config CLERUM_ATTACHMENT_FILE_MAX_BYTES default'+ )+ expect(Number(literal.replaceAll('_', ''))).toBe(+ constantValue(sources.mcpHost, 'MAX_FILE_DECODED_BYTES', 'mcp-host')+ )+ })+})diff --git a/tests/e2e/package-lock.json b/tests/e2e/package-lock.jsonindex 3e074b47d..c4e9efb72 100644--- a/tests/e2e/package-lock.json+++ b/tests/e2e/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-e2e-tests",- "version": "0.1.96",+ "version": "0.1.97","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-e2e-tests",- "version": "0.1.96",+ "version": "0.1.97","devDependencies": {"@clerum/llm-provider-attempt-contract": "file:../../packages/llm-provider-attempt-contract","@types/jsonwebtoken": "^9.0.10",diff --git a/tests/e2e/package.json b/tests/e2e/package.jsonindex 125b1df5d..e3c2c5a98 100644--- a/tests/e2e/package.json+++ b/tests/e2e/package.json@@ -1,6 +1,6 @@{"name": "clerum-e2e-tests",- "version": "0.1.96",+ "version": "0.1.97","private": true,"type": "module","scripts": {