Skip to content

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

TypeScript

fix(host): cap the attachment notice reserve at half of the turn budget

Alfredo Lopez60e591125c16
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index b8d39b9eb..2e0a546d6 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.503",
+ "version": "0.1.504",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.503",
+ "version": "0.1.504",
"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 7af022fab..3881d4e89 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.503",
+ "version": "0.1.504",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/core/attachments/__tests__/attachmentReadBudget.test.ts b/mcp-host/src/core/attachments/__tests__/attachmentReadBudget.test.ts
index a7f9e00b4..372c3a338 100644
--- a/mcp-host/src/core/attachments/__tests__/attachmentReadBudget.test.ts
+++ b/mcp-host/src/core/attachments/__tests__/attachmentReadBudget.test.ts
@@ -17,12 +17,50 @@ describe('attachment turn ledger', () => {
})
it('limits calls to 32 and reserves complete-message notices', () => {
const ledger = new AttachmentReadLedger()
- expect(ledger.pageAllowance(10_000, 80)).toBe(360)
+ // 33 notices of 80 tokens exceed half of the 3_000-token turn, so the
+ // reserve is capped at floor(1_500 / 80) = 18 notices; the page cap binds.
+ expect(ledger.pageAllowance(10_000, 80)).toBe(1_000)
+ ledger.restore({ reads: 0, spentTokens: 1_000, bytesRead: 0 })
+ expect(ledger.pageAllowance(10_000, 80)).toBe(3_000 - 1_000 - 18 * 80)
+ ledger.reset()
for (let i = 0; i < 32; i++) expect(ledger.beginRead()).toBe(true)
expect(ledger.beginRead()).toBe(false)
expect(ledger.snapshot().reads).toBe(32)
expect(ledger.pageAllowance(10_000, 80)).toBe(1_000)
})
+ it('leaves a first page on an 8192-token window with a measured 219-token notice', () => {
+ const ledger = new AttachmentReadLedger()
+ expect(ledger.beginRead()).toBe(true)
+ // turn 2_457, reserve min(32, floor(1_228 / 219) = 5) * 219 = 1_095.
+ expect(ledger.pageAllowance(8_192, 219)).toBe(819)
+ })
+ it('never reserves more than half of the turn budget for notices', () => {
+ for (const windowTokens of [4_096, 8_192, 16_384, 32_768, 128_000, 1_000_000]) {
+ const { pageTokens, turnTokens } = attachmentReadBudgets(windowTokens)
+ for (const noticeCost of [1, 80, 219, 339]) {
+ if (noticeCost > Math.floor(turnTokens / 2)) continue
+ for (const reads of [0, 1, 16, 31, 32]) {
+ const ledger = new AttachmentReadLedger()
+ ledger.restore({ reads, spentTokens: 0, bytesRead: 0 })
+ // At most half of the turn is held back for notices.
+ expect(ledger.pageAllowance(windowTokens, noticeCost)).toBeGreaterThanOrEqual(
+ Math.min(pageTokens, turnTokens - Math.floor(turnTokens / 2))
+ )
+ // At least one notice is always held back.
+ ledger.restore({ reads, spentTokens: turnTokens - noticeCost, bytesRead: 0 })
+ expect(ledger.pageAllowance(windowTokens, noticeCost)).toBe(0)
+ }
+ }
+ }
+ })
+ it('refuses a window too small to reserve one notice, with a clear message', () => {
+ const ledger = new AttachmentReadLedger()
+ // turn 30, half 15: a 16-token notice cannot be reserved even once.
+ expect(() => ledger.pageAllowance(100, 16)).toThrow(/too small to reserve/i)
+ expect(() => ledger.pageAllowance(100, 0)).toThrow(/notice cost/i)
+ // Witness: the same window with a notice that fits half the turn returns a page.
+ expect(ledger.pageAllowance(100, 15)).toBe(10)
+ })
it('charges successful emissions and refuses an over-budget debit without mutation', () => {
const ledger = new AttachmentReadLedger()
expect(() => ledger.debit(10_000, 1_001, 1)).toThrow()
diff --git a/mcp-host/src/core/attachments/attachmentReadBudget.ts b/mcp-host/src/core/attachments/attachmentReadBudget.ts
index 23d8d136b..48780ea68 100644
--- a/mcp-host/src/core/attachments/attachmentReadBudget.ts
+++ b/mcp-host/src/core/attachments/attachmentReadBudget.ts
@@ -98,10 +98,22 @@ export class AttachmentReadLedger {
}
pageAllowance(windowTokens: number, noticeCost: number): number {
- if (!boundedCount(noticeCost)) throw new Error('Invalid attachment notice cost')
+ if (!boundedCount(noticeCost) || noticeCost === 0) {
+ throw new Error('Invalid attachment notice cost')
+ }
const limits = attachmentReadBudgets(windowTokens)
- // Leave one notice for every remaining call and the first exhausted call.
- const reserve = (MAX_ATTACHMENT_READS_PER_TURN - this.state.reads + 1) * noticeCost
+ // Leave one notice for every remaining call and the first exhausted call,
+ // but never more than half of the turn: on a small window 33 notices would
+ // exceed the whole turn and no page could ever be emitted. Once the
+ // reserved notices are spent, the finalize fence stops the turn.
+ const affordableNotices = Math.floor(Math.floor(limits.turnTokens / 2) / noticeCost)
+ if (affordableNotices < 1) {
+ throw new Error(
+ `Attachment read context window of ${windowTokens} tokens is too small to reserve a ${noticeCost}-token budget notice`
+ )
+ }
+ const reserve =
+ Math.min(MAX_ATTACHMENT_READS_PER_TURN - this.state.reads + 1, affordableNotices) * noticeCost
return Math.max(
0,
Math.min(limits.pageTokens, limits.turnTokens - this.state.spentTokens - reserve)
diff --git a/mcp-host/src/core/tools/__tests__/attachmentRead.budget.test.ts b/mcp-host/src/core/tools/__tests__/attachmentRead.budget.test.ts
index 79e37485d..c0c8ac8c9 100644
--- a/mcp-host/src/core/tools/__tests__/attachmentRead.budget.test.ts
+++ b/mcp-host/src/core/tools/__tests__/attachmentRead.budget.test.ts
@@ -6,10 +6,11 @@
* fitter. Every test drives the real execute -> finalize contract once.
*/
import { describe, expect, it } from 'vitest'
-import { createHash } from 'node:crypto'
+import { createHash, randomUUID } from 'node:crypto'
import { validateIncomingAttachments } from '../../../agent/incomingAttachments'
import type { IncomingMessage } from '../../../server'
-import { AttachmentReadLedger } from '../../attachments/attachmentReadBudget'
+import { AttachmentReadLedger, attachmentReadBudgets } from '../../attachments/attachmentReadBudget'
+import { toolMessageBudgetTokens } from '../../extensions/contextManager'
import { BasicSafety } from '../../safety/safety'
import type { Attachment, ToolResult } from '../../types'
import { AttachmentReadTool } from '../attachmentRead'
@@ -196,11 +197,16 @@ describe('C16 page fitting', () => {
let offset = 0
const limits: string[] = []
- for (let page = 0; page < 3; page++) {
+ for (let page = 0; page < 32; page++) {
const { outputBody } = await runRead(tool, { attachmentId: 'file-turn', offset })
+ if (outputBody.kind !== 'text') {
+ expect(outputBody.kind).toBe('read_budget_exhausted')
+ break
+ }
limits.push(outputBody.limit as string)
offset += (outputBody.byteRange as { length: number }).length
}
+ expect(limits.length).toBeGreaterThanOrEqual(2)
expect(limits[0]).toBe('page_budget')
expect(limits[limits.length - 1]).toBe('turn_budget')
expect(ledger.snapshot().spentTokens).toBeLessThanOrEqual(Math.floor(WINDOW_TOKENS * 0.3))
@@ -246,6 +252,111 @@ describe('C16 read count and exhaustion', () => {
})
})
+describe('C16 small context windows under the production tool-message measurement', () => {
+ const SMALL_WINDOW = 8_192
+ const CALL_ID = 'toolu_01AbCdEfGhIjKlMnOpQrStUv'
+ // The Host's own measurement: rendered content inside a complete tool message.
+ const measureMessage = (content: string): number =>
+ toolMessageBudgetTokens(
+ { role: 'tool', name: TOOL_NAME, tool_call_id: CALL_ID, content },
+ undefined,
+ false
+ )
+
+ async function runMeasured(tool: AttachmentReadTool, params: Record<string, unknown>) {
+ const output = await tool.execute(params, {
+ onOutput: () => {},
+ measureResult: raw => measureMessage(renderContent(raw)),
+ })
+ const content = renderContent(output.content)
+ const finalized = tool.finalizeResult!(
+ {
+ tool_call_id: CALL_ID,
+ name: TOOL_NAME,
+ content,
+ is_error: output.is_error,
+ metadata: output.metadata,
+ rawContent: output.content,
+ emittedMessageCost: measureMessage(content),
+ },
+ { measureContent: measureMessage, renderContent }
+ )
+ return {
+ finalized,
+ body: JSON.parse(finalized.rawContent as string) as Record<string, unknown>,
+ }
+ }
+
+ it('returns an 11-byte file on an 8192-token window instead of an exhausted notice', async () => {
+ const id = randomUUID()
+ const [file] = admitted([rawFile(id, 'hello.txt', 'text/plain', Buffer.from('hello world'))])
+ const { tool, ledger } = toolFor([file!], { windowTokens: SMALL_WINDOW })
+
+ const { finalized, body } = await runMeasured(tool, { attachmentId: id })
+ expect(body.kind).toBe('text')
+ expect(body.text).toBe('hello world')
+ expect(finalized.is_error).toBe(false)
+ expect(ledger.snapshot().bytesRead).toBe(11)
+ expect(ledger.snapshot().spentTokens).toBe(finalized.emittedMessageCost)
+ })
+
+ it('pages, then answers with reserved notices, then stops the turn at the fence', async () => {
+ const id = randomUUID()
+ const [file] = admitted([rawFile(id, 'long.txt', 'text/plain', Buffer.alloc(400_000, 'q'))])
+ const { tool, ledger } = toolFor([file!], { windowTokens: SMALL_WINDOW })
+ const { turnTokens } = attachmentReadBudgets(SMALL_WINDOW)
+
+ const kinds: string[] = []
+ let offset = 0
+ let stop: unknown = null
+ for (let call = 0; call < 200 && stop === null; call++) {
+ const before = ledger.snapshot().spentTokens
+ try {
+ const { body } = await runMeasured(tool, { attachmentId: id, offset })
+ kinds.push(body.kind as string)
+ if (body.kind === 'text') offset += (body.byteRange as { length: number }).length
+ // Every emitted message is charged, and the turn envelope is never crossed.
+ expect(ledger.snapshot().spentTokens).toBeGreaterThan(before)
+ expect(ledger.snapshot().spentTokens).toBeLessThanOrEqual(turnTokens)
+ } catch (error) {
+ stop = error
+ }
+ }
+ expect(kinds[0]).toBe('text')
+ const firstNotice = kinds.indexOf('read_budget_exhausted')
+ expect(firstNotice).toBeGreaterThan(0)
+ expect(kinds.slice(firstNotice).every(kind => kind === 'read_budget_exhausted')).toBe(true)
+ expect(kinds.length - firstNotice).toBeGreaterThanOrEqual(2)
+ expect(String(stop)).toMatch(/notice cannot fit/)
+ })
+
+ it('keeps error and binary results no larger than the exhausted notice (regression guard)', async () => {
+ const textId = randomUUID()
+ const binaryId = randomUUID()
+ const [textFile, binaryFile] = admitted([
+ rawFile(textId, 'aé.txt', 'text/plain', Buffer.from('aé!')),
+ rawFile(binaryId, 'blob.bin', 'application/octet-stream', Buffer.alloc(64, 0)),
+ ])
+ const ledger = new AttachmentReadLedger()
+ const { tool } = toolFor([textFile!, binaryFile!], { windowTokens: 100_000, ledger })
+
+ const invalid = await runMeasured(tool, { attachmentId: textId, offset: 2 })
+ const binary = await runMeasured(tool, { attachmentId: binaryId })
+ ledger.restore({ reads: 32, spentTokens: ledger.snapshot().spentTokens, bytesRead: 0 })
+ const notice = await runMeasured(tool, { attachmentId: textId, offset: 11_534_336 })
+
+ expect(invalid.body.error).toBe('range_invalid')
+ expect(binary.body.kind).toBe('binary')
+ expect(notice.body.kind).toBe('read_budget_exhausted')
+ expect(invalid.finalized.emittedMessageCost).toBeLessThanOrEqual(
+ notice.finalized.emittedMessageCost!
+ )
+ expect(binary.finalized.emittedMessageCost).toBeLessThanOrEqual(
+ notice.finalized.emittedMessageCost!
+ )
+ })
+})
+
describe('C16 finalize fence', () => {
it('replaces post-transform growth with a trusted exhausted notice at the original offset', async () => {
const [file] = admitted([