Skip to content

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

TypeScript

fix(mcp-host): document spillover in clerum__attachment_read and page without re-decoding

Alfredo Lopez9219625312b7
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 61ffa4f2f..b9a4efe43 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.449",
+ "version": "0.1.450",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.449",
+ "version": "0.1.450",
"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 46a0ab59c..696762c7a 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.449",
+ "version": "0.1.450",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/agent/taskExecutor.ts b/mcp-host/src/agent/taskExecutor.ts
index 0723b2e3d..fd0d8ea95 100644
--- a/mcp-host/src/agent/taskExecutor.ts
+++ b/mcp-host/src/agent/taskExecutor.ts
@@ -2019,7 +2019,12 @@ export class TaskExecutor {
this.deps.failover?.policy.fallbacks
)
const nativeRegistry = new NativeToolRegistry(
- appConfig.nativeTool,
+ // The spillover threshold is a top-level setting; clerum__attachment_read
+ // states it in its description (#666).
+ {
+ ...appConfig.nativeTool,
+ toolSpilloverThresholdBytes: appConfig.toolSpilloverThresholdBytes,
+ },
this.conversation!.id,
this.deps.cronScheduler ?? undefined,
this.task.sourceMessage,
diff --git a/mcp-host/src/core/interfaces.ts b/mcp-host/src/core/interfaces.ts
index e93b68ad5..f06ba3954 100644
--- a/mcp-host/src/core/interfaces.ts
+++ b/mcp-host/src/core/interfaces.ts
@@ -255,4 +255,8 @@ export interface NativeToolConfig {
/** Per-call byte ceiling of `clerum__attachment_read` (#666). Registering the
* tool for a message with `kind:'file'` attachments requires it. */
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__/toolUseLoopSingleTool.attachmentRead.test.ts b/mcp-host/src/core/orchestration/__tests__/toolUseLoopSingleTool.attachmentRead.test.ts
new file mode 100644
index 000000000..ab822c25a
--- /dev/null
+++ b/mcp-host/src/core/orchestration/__tests__/toolUseLoopSingleTool.attachmentRead.test.ts
@@ -0,0 +1,196 @@
+/**
+ * #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.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { createHash } from 'node:crypto'
+import * as fs from 'node:fs/promises'
+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 { BasicSafety } from '../../safety/safety'
+import { DefaultToolOutputProcessor } from '../../safety/toolOutputProcessor'
+import { SpilloverStorage, type SpilloverSummary } from '../../spillover'
+import { AttachmentReadTool } from '../../tools/attachmentRead'
+import { SimpleEventEmitter } from '../eventEmitter'
+import { executeSingleTool } from '../toolUseLoop'
+
+const THRESHOLD = 8192
+const PAGE_BYTES = 20 * 1024
+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.
+const WRAPPER_OPEN = '<tool_output name="clerum__attachment_read" sanitized="false">\n'
+const WRAPPER_CLOSE = '\n</tool_output>'
+
+function attachedFile(bytes: Buffer) {
+ const result = validateIncomingAttachments(
+ [
+ {
+ id: ATTACHMENT_ID,
+ kind: 'file',
+ mimeType: 'text/plain',
+ detectedMediaType: 'text/plain',
+ encoding: 'base64',
+ dataBase64: bytes.toString('base64'),
+ filename: 'notes.txt',
+ sizeBytes: bytes.length,
+ digest: { algorithm: 'sha256', hex: createHash('sha256').update(bytes).digest('hex') },
+ },
+ ],
+ { maxCount: 20, maxBytes: 1_000_000, maxFileBytes: 3_145_728, messageId: MESSAGE_ID }
+ )
+ if (!result.ok) throw new Error(`fixture rejected: ${result.error.code}`)
+ 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)
+}
+
+describe('executeSingleTool — clerum__attachment_read and the spillover threshold (#666)', () => {
+ let workspace: string
+ let storage: SpilloverStorage
+
+ beforeEach(async () => {
+ workspace = await fs.mkdtemp(path.join(os.tmpdir(), 'attachment-read-spill-'))
+ storage = new SpilloverStorage({
+ workspacePath: workspace,
+ thresholdBytes: THRESHOLD,
+ ttlMs: 60_000,
+ gcIntervalMs: 0,
+ })
+ })
+
+ afterEach(async () => {
+ storage.stopGc()
+ 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)
+ const registry: ToolRegistry = {
+ get: name => (name === tool.name() ? tool : null),
+ listDefinitions: () => [],
+ register: () => undefined,
+ }
+ const safety = new BasicSafety()
+ return executeSingleTool(
+ {
+ id: callId,
+ name: 'clerum__attachment_read',
+ arguments: { attachmentId: ATTACHMENT_ID, ...args },
+ },
+ {
+ toolRegistry: registry,
+ toolOutputProcessor: new DefaultToolOutputProcessor(safety),
+ safety,
+ events: new SimpleEventEmitter(),
+ toolTimeout: 1000,
+ progressReporter: undefined,
+ toolProgressInterval: 0,
+ spilloverStorage: storage,
+ taskId: TASK_ID,
+ }
+ )
+ }
+
+ it('spills a 20 KB page into a summary whose head carries the paging fields', 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 })
+
+ 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')
+ })
+
+ it('reports truncated:false in the head of the last spilled page', 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', {
+ 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))
+ })
+
+ 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))
+
+ const result = await readPage(attachment, 'read-3', { maxBytes: 1024 })
+
+ 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',
+ })
+ })
+})
diff --git a/mcp-host/src/core/tools/__tests__/attachmentRead.test.ts b/mcp-host/src/core/tools/__tests__/attachmentRead.test.ts
index d9134b9ab..adf545b40 100644
--- a/mcp-host/src/core/tools/__tests__/attachmentRead.test.ts
+++ b/mcp-host/src/core/tools/__tests__/attachmentRead.test.ts
@@ -2,14 +2,27 @@
* #666 — `clerum__attachment_read`. Attachments are built by the real admission
* validator, so every `FileReferenceV1` here is one the host would produce.
*/
-import { describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
import { createHash } from 'node:crypto'
import { validateIncomingAttachments } from '../../../agent/incomingAttachments'
+import { decodeTextContent } from '../../../internalTools/textContent'
import type { IncomingMessage } from '../../../server'
import type { Attachment } from '../../types'
import { AttachmentReadTool } from '../attachmentRead'
+// Pass-through spy: the whole-file text check keeps its real behaviour, and
+// the paging test counts how often it runs.
+vi.mock('../../../internalTools/textContent', async importOriginal => {
+ const original = await importOriginal<typeof import('../../../internalTools/textContent')>()
+ return { ...original, decodeTextContent: vi.fn(original.decodeTextContent) }
+})
+
+afterEach(() => {
+ vi.mocked(decodeTextContent).mockClear()
+})
+
const READ_LIMIT = 262_144
+const SPILLOVER_THRESHOLD = 8192
const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
function rawFile(id: string, filename: string, mimeType: string, bytes: Buffer) {
@@ -37,7 +50,11 @@ function admitted(raw: unknown[]): Attachment[] {
return result.attachments!
}
-function toolFor(attachments: Attachment[], limit = READ_LIMIT): AttachmentReadTool {
+function toolFor(
+ attachments: Attachment[],
+ limit = READ_LIMIT,
+ spilloverThresholdBytes: number | null = SPILLOVER_THRESHOLD
+): AttachmentReadTool {
const message: IncomingMessage = {
content: 'Analyze the attached file',
channelType: 'rpc',
@@ -48,7 +65,7 @@ function toolFor(attachments: Attachment[], limit = READ_LIMIT): AttachmentReadT
hostRef: 'host-1',
attachments,
}
- return new AttachmentReadTool(message, limit)
+ return new AttachmentReadTool(message, limit, spilloverThresholdBytes)
}
async function read(tool: AttachmentReadTool, params: Record<string, unknown>) {
@@ -70,19 +87,24 @@ describe('clerum__attachment_read', () => {
})
})
- it('returns the whole text of a small text file with its reference', async () => {
+ it('returns the whole text of a small text file with its identity', async () => {
const [file] = admitted([
rawFile('file-1', 'notes.txt', 'text/plain', Buffer.from(`hello ${SENTINEL}\n`)),
])
const { output, body } = await read(toolFor([file!]), { attachmentId: 'file-1' })
expect(output.is_error).toBe(false)
expect(body).toEqual({
- reference: file!.fileReference,
+ attachmentId: 'file-1',
+ referenceId: file!.fileReference!.id,
kind: 'text',
text: `hello ${SENTINEL}\n`,
byteRange: { offset: 0, length: Buffer.byteLength(`hello ${SENTINEL}\n`) },
truncated: false,
})
+ // The file name stays on the attached_file line; the page does not repeat it.
+ // Witness: the page text is in the same output.
+ expect(output.content).toContain(SENTINEL)
+ expect(output.content).not.toContain('notes.txt')
})
it('returns a typed binary result for a reader=none file without decoding it', async () => {
@@ -92,7 +114,8 @@ describe('clerum__attachment_read', () => {
const { output, body } = await read(toolFor([file!]), { attachmentId: 'file-1' })
expect(output.is_error).toBe(false)
expect(body).toEqual({
- reference: file!.fileReference,
+ attachmentId: 'file-1',
+ referenceId: file!.fileReference!.id,
kind: 'binary',
reader: 'none',
reason: 'no_reader_for_class',
@@ -116,7 +139,8 @@ describe('clerum__attachment_read', () => {
const { output, body } = await read(toolFor([file!]), { attachmentId: 'file-1' })
expect(output.is_error).toBe(false)
expect(body).toEqual({
- reference: file!.fileReference,
+ attachmentId: 'file-1',
+ referenceId: file!.fileReference!.id,
kind: 'binary',
reader: 'none',
reason: 'text_decode_rejected',
@@ -168,6 +192,67 @@ describe('clerum__attachment_read', () => {
expect(offset).toBe(bytes.length)
})
+ it('runs the whole-file text check once and decodes only the page on later calls', async () => {
+ const [file] = admitted([
+ rawFile('file-1', 'notes.txt', 'text/plain', Buffer.from(`abcdef${SENTINEL}`)),
+ ])
+ const tool = toolFor([file!])
+ const first = await read(tool, { attachmentId: 'file-1', maxBytes: 3 })
+ const second = await read(tool, { attachmentId: 'file-1', offset: 3, maxBytes: 3 })
+ // Witness: both pages came back from the same file.
+ expect(first.body.text).toBe('abc')
+ expect(second.body.text).toBe('def')
+ expect(decodeTextContent).toHaveBeenCalledTimes(1)
+ })
+
+ it('ends a page before a 4-byte character that does not fit', async () => {
+ // 'a😀b' = 61 F0 9F 98 80 62: a 4-byte page from offset 0 ends inside the emoji.
+ const [file] = admitted([rawFile('file-1', 'emoji.txt', 'text/plain', Buffer.from('a😀b'))])
+ const tool = toolFor([file!])
+ const first = await read(tool, { attachmentId: 'file-1', maxBytes: 4 })
+ expect(first.body).toMatchObject({
+ text: 'a',
+ byteRange: { offset: 0, length: 1 },
+ truncated: true,
+ })
+ const second = await read(tool, { attachmentId: 'file-1', offset: 1, maxBytes: 4 })
+ expect(second.body).toMatchObject({
+ text: '😀',
+ byteRange: { offset: 1, length: 4 },
+ truncated: true,
+ })
+ const narrow = await read(tool, { attachmentId: 'file-1', offset: 1, maxBytes: 3 })
+ expect(narrow.body.error).toBe('range_invalid')
+ })
+
+ it('orders a text result so the text comes after the page fields', async () => {
+ const [file] = admitted([rawFile('file-1', 'notes.txt', 'text/plain', Buffer.from(SENTINEL))])
+ const { output } = await read(toolFor([file!]), { attachmentId: 'file-1' })
+ expect(Object.keys(JSON.parse(output.content))).toEqual([
+ 'attachmentId',
+ 'referenceId',
+ 'kind',
+ 'byteRange',
+ 'truncated',
+ 'text',
+ ])
+ })
+
+ 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('does not mention spillover when this execution has no spillover storage', () => {
+ const description = toolFor([], READ_LIMIT, null).description()
+ // Witness: the description is the tool's full text.
+ expect(description).toContain('Files with reader=text return UTF-8 text')
+ expect(description).not.toContain('spillover')
+ })
+
it('drops a byte order mark only at the start of the file', async () => {
const bytes = Buffer.concat([
Buffer.from([0xef, 0xbb, 0xbf]),
diff --git a/mcp-host/src/core/tools/attachmentRead.ts b/mcp-host/src/core/tools/attachmentRead.ts
index 30bd0105d..9f712d2c0 100644
--- a/mcp-host/src/core/tools/attachmentRead.ts
+++ b/mcp-host/src/core/tools/attachmentRead.ts
@@ -2,7 +2,7 @@
* #666 — `clerum__attachment_read` native tool.
*
* Reads a `kind:'file'` attachment of the message that started this turn. The
- * turn context lists those files (`attached_file: id=… reader=…`); the content
+ * turn context lists those files (`attached_file: id="…" … reader=…`); the content
* never reaches the model up front, only through this tool, and its output is
* sanitized like any other untrusted tool result.
*
@@ -25,15 +25,30 @@ import type { ToolOutput } from '../types'
export type AttachmentReadErrorCode = 'attachment_not_found' | 'range_invalid'
+// The result names the file by `attachmentId` (what the model passes to read
+// again) and `referenceId` (the FileReferenceV1 id, which pins the bytes by
+// 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`.
export type AttachmentReadResult =
| {
- reference: FileReferenceV1
+ attachmentId: string
+ referenceId: FileReferenceV1['id']
kind: 'text'
- text: string
byteRange: { offset: number; length: number }
truncated: boolean
+ text: string
+ }
+ | {
+ attachmentId: string
+ referenceId: FileReferenceV1['id']
+ kind: 'binary'
+ reader: 'none'
+ reason: 'no_reader_for_class' | 'text_decode_rejected'
}
- | { reference: FileReferenceV1; kind: 'binary'; reader: 'none'; reason: string }
const ERROR_MESSAGES: Record<AttachmentReadErrorCode, string> = {
attachment_not_found: 'No file with this attachmentId is attached to the current message.',
@@ -46,9 +61,17 @@ function isUtf8Continuation(byte: number): boolean {
}
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).
+ */
constructor(
private readonly sourceMessage: IncomingMessage,
- private readonly maxBytesPerCall: number
+ private readonly maxBytesPerCall: number,
+ private readonly spilloverThresholdBytes: number | null
) {}
name(): string {
@@ -59,6 +82,11 @@ 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. ') +
'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.'
@@ -114,6 +142,7 @@ export class AttachmentReadTool implements Tool {
)
const reference = attachment?.fileReference
if (!attachment || !reference) return this.error('attachment_not_found', start)
+ const identity = { attachmentId: attachment.id, referenceId: reference.id }
const offset = params.offset ?? 0
const maxBytes = params.maxBytes ?? this.maxBytesPerCall
@@ -131,15 +160,15 @@ export class AttachmentReadTool implements Tool {
if (reference.reader === 'none') {
return this.ok(
- { reference, kind: 'binary', reader: 'none', reason: 'no_reader_for_class' },
+ { ...identity, kind: 'binary', reader: 'none', reason: 'no_reader_for_class' },
start
)
}
- const bytes = Buffer.from(attachment.dataBase64, 'base64')
- if (decodeTextContent(bytes) === null) {
+ const { bytes, isText } = this.decode(attachment.id, attachment.dataBase64)
+ if (!isText) {
return this.ok(
- { reference, kind: 'binary', reader: 'none', reason: 'text_decode_rejected' },
+ { ...identity, kind: 'binary', reader: 'none', reason: 'text_decode_rejected' },
start
)
}
@@ -158,16 +187,27 @@ export class AttachmentReadTool implements Tool {
)
return this.ok(
{
- reference,
+ ...identity,
kind: 'text',
- text,
byteRange: { offset, length: end - offset },
truncated: end < bytes.length,
+ text,
},
start
)
}
+ // The whole-file text check runs once per attachment; each page then
+ // decodes only its own slice.
+ private decode(attachmentId: string, dataBase64: string): { bytes: Buffer; isText: boolean } {
+ const cached = this.decoded.get(attachmentId)
+ if (cached) return cached
+ const bytes = Buffer.from(dataBase64, 'base64')
+ const entry = { bytes, isText: decodeTextContent(bytes) !== null }
+ this.decoded.set(attachmentId, entry)
+ return entry
+ }
+
private ok(result: AttachmentReadResult, start: number): ToolOutput {
return { content: JSON.stringify(result), duration_ms: Date.now() - start, is_error: false }
}
diff --git a/mcp-host/src/core/tools/nativeToolRegistry.ts b/mcp-host/src/core/tools/nativeToolRegistry.ts
index c2c780af0..368698bde 100644
--- a/mcp-host/src/core/tools/nativeToolRegistry.ts
+++ b/mcp-host/src/core/tools/nativeToolRegistry.ts
@@ -278,7 +278,20 @@ export class NativeToolRegistry implements ToolRegistry {
'NativeToolConfig.attachmentTextReadMaxBytes is required for file attachments'
)
}
- this.register(new AttachmentReadTool(sourceMessage, maxBytes))
+ 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
+ )
+ )
}
const envGetter = (key: string): string | undefined => {
diff --git a/mcp-host/src/internalTools/textContent.ts b/mcp-host/src/internalTools/textContent.ts
index 52ebd5599..484e610aa 100644
--- a/mcp-host/src/internalTools/textContent.ts
+++ b/mcp-host/src/internalTools/textContent.ts
@@ -31,7 +31,7 @@ export function decodeTextContent(bytes: Uint8Array): string | null {
try {
// TextDecoder already drops a UTF-8 BOM; strip again so classification
// and the model see the same contract.
- text = new TextDecoder('utf-8', { fatal: true }).decode(bytes).replace(/^/, '')
+ text = new TextDecoder('utf-8', { fatal: true }).decode(bytes).replace(/^\uFEFF/, '')
} catch {
return null
}