Skip to content

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.ts
index 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.ts
index 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_ROOT
export 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.ts
index 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 t
buffer: 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 | undefined
let 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.ts
index 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.tsx
index 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.tsx
index 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.composerFileAttachments
expect(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.ts
index 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.ts
index 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.ts
index 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.md
index 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 attachment
budgets (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 control
routes keep the 10 MB ordinary JSON cap. The proxy's larger
parser 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.md
index 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 px
model bound. Exercise 5 MiB, 12 MiB (exceptional, above 10 MiB), 10+5 MiB
and 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 an
anonymous, 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 from
diff --git a/external-rest-api/src/releaseManifest.ts b/external-rest-api/src/releaseManifest.ts
index 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.md
index 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 CRD
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 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.json
index 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.ts
index 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 * MIB
const 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.ts
index 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.ts
index 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 = 20
diff --git a/mcp-host/src/agent/taskExecutor.ts b/mcp-host/src/agent/taskExecutor.ts
index 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.ts
index 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.ts
index 66de689af..a03284b51 100644
--- a/mcp-host/src/config.ts
+++ b/mcp-host/src/config.ts
@@ -240,7 +240,11 @@ export interface Config {
enableResponseAttachments: boolean
attachmentMaxCount: number
attachmentMaxBytes: 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): HostSpe
const 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.ts
index 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.ts
index 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.ts
index 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 = 8192
const PAGE_BYTES = 20 * 1024
+const READ_LIMIT = 65_536
const 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: string
let 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 thresh
await 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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_536
const 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 boolean
calls += 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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) : null
diff --git a/mcp-host/src/server.ts b/mcp-host/src/server.ts
index 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 * 1024
const MAX_NON_IMAGE_BODY_BYTES = 6 * 1024 * 1024
const MAX_CHAT_IMAGES = 20
const MAX_IMAGE_DECODED_BYTES = 16 * 1024 * 1024
const 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.json
index 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.json
index 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.ts
index 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.ts
index 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 * 1024
const MAX_CHAT_IMAGES = 20
const MAX_IMAGE_DECODED_BYTES = 16 * 1024 * 1024
const 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.md
index 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 hex
characters of the SHA-256 of the text in that result. The prompt alone can never
produce 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-text
or 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.mjs
index 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 += 1
sequence += 1
const 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.mjs
index 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 co
imageSha256: 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.mjs
index 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 a
imageSha256: 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.json
index 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.json
index 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.ts
new file mode 100644
index 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.json
index 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.json
index 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": {