Skip to content

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

TypeScript

fix(host): answer attachment reads past the turn budget with a bounded notice overdraft

Alfredo Lopeze756e11915ee
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 642e04a30..0ad0982c9 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.505",
+ "version": "0.1.506",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.505",
+ "version": "0.1.506",
"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 2ba1fba6a..3cb8a689f 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.505",
+ "version": "0.1.506",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/agent/__tests__/attachmentRead.approvalBudget.test.ts b/mcp-host/src/agent/__tests__/attachmentRead.approvalBudget.test.ts
index 8fcedfe8e..ef41b076d 100644
--- a/mcp-host/src/agent/__tests__/attachmentRead.approvalBudget.test.ts
+++ b/mcp-host/src/agent/__tests__/attachmentRead.approvalBudget.test.ts
@@ -258,15 +258,19 @@ describe('attachment budget through real approval persistence', () => {
expect(await readFile(join(f.dir, 'effects.txt'), 'utf8')).toBe('approved\n')
})
it.each(['missing', 'corrupt', 'empty'] as const)(
- 'rejects new reads with an unprovable %s carrier',
+ 'answers new reads with notices after an unprovable %s carrier',
async mode => {
const f = await fixture()
const next = await f.cold(mode)
- expect(next.value.executorState).toBe('failed')
- expect(next.onFail).toHaveBeenCalledTimes(1)
- // The task fails because the read was refused, not for an unrelated reason.
- expect(next.onFail.mock.calls[0]![1].message).toMatch(/notice cannot fit/)
- expect(f.messages().some(m => m.tool_call_id === 'read-after-0')).toBe(false)
+ expect(next.onFail.mock.calls.map(call => call[1])).toEqual([])
+ expect(next.value.executorState).toBe('completed')
+ // Liveness: the resumed turn did call the tool, and every call got a notice.
+ const reads = f.messages().filter(m => m.tool_call_id?.startsWith('read-after-'))
+ expect(reads).toHaveLength(32)
+ for (const read of reads) {
+ expect(read.content).toContain('read_budget_exhausted')
+ expect(read.content).not.toContain('Public first-page sentinel')
+ }
}
)
it('preserves conservative exhaustion when a legacy row requires another approval', async () => {
diff --git a/mcp-host/src/core/attachments/__tests__/attachmentReadBudget.test.ts b/mcp-host/src/core/attachments/__tests__/attachmentReadBudget.test.ts
index 372c3a338..d84be4df6 100644
--- a/mcp-host/src/core/attachments/__tests__/attachmentReadBudget.test.ts
+++ b/mcp-host/src/core/attachments/__tests__/attachmentReadBudget.test.ts
@@ -8,6 +8,30 @@ import {
const zero = { reads: 0, spentTokens: 0, bytesRead: 0 }
+describe('notice overdraft', () => {
+ const WINDOW = 10_000 // page 1000, turn 3000, ceiling 4500
+
+ it('charges a notice past the turn up to half a turn more, without reads or bytes', () => {
+ const ledger = new AttachmentReadLedger()
+ ledger.restore({ reads: 32, spentTokens: 3_000, bytesRead: 77 })
+ expect(ledger.canEmit(WINDOW, 100)).toBe(false)
+ ledger.debitNotice(WINDOW, 1_000)
+ ledger.debitNotice(WINDOW, 500)
+ expect(ledger.snapshot()).toEqual({ reads: 32, spentTokens: 4_500, bytesRead: 77 })
+ expect(() => ledger.debitNotice(WINDOW, 1)).toThrow(/notice cannot fit/)
+ expect(ledger.snapshot().spentTokens).toBe(4_500)
+ })
+
+ it('refuses a notice larger than one page even with overdraft left', () => {
+ const ledger = new AttachmentReadLedger()
+ ledger.restore({ reads: 0, spentTokens: 3_000, bytesRead: 0 })
+ expect(() => ledger.debitNotice(WINDOW, 1_001)).toThrow(/notice cannot fit/)
+ // Witness: a page-sized notice is accepted on the same ledger.
+ ledger.debitNotice(WINDOW, 1_000)
+ expect(ledger.snapshot().spentTokens).toBe(4_000)
+ })
+})
+
describe('attachment turn ledger', () => {
it('derives the 10% page and 30% turn limits', () => {
expect(attachmentReadBudgets(10_000)).toEqual({ pageTokens: 1_000, turnTokens: 3_000 })
diff --git a/mcp-host/src/core/attachments/attachmentReadBudget.ts b/mcp-host/src/core/attachments/attachmentReadBudget.ts
index 48780ea68..de4eb6fab 100644
--- a/mcp-host/src/core/attachments/attachmentReadBudget.ts
+++ b/mcp-host/src/core/attachments/attachmentReadBudget.ts
@@ -138,4 +138,25 @@ export class AttachmentReadLedger {
this.state.spentTokens += cost
this.state.bytesRead += bytesRead
}
+
+ /**
+ * Charges a trusted exhausted notice that no longer fits the turn. Notices
+ * read no bytes and do not count as reads, so a model that keeps calling
+ * after the budget binds gets an answer instead of a failed task. The
+ * overdraft stops at half a turn above the turn budget; past it the caller
+ * stops the turn.
+ */
+ debitNotice(windowTokens: number, cost: number): void {
+ const limits = attachmentReadBudgets(windowTokens)
+ const ceiling = limits.turnTokens + Math.floor(limits.turnTokens / 2)
+ if (
+ !boundedCount(cost) ||
+ cost > limits.pageTokens ||
+ !Number.isSafeInteger(this.state.spentTokens + cost) ||
+ this.state.spentTokens + cost > ceiling
+ ) {
+ throw new Error('Attachment read notice cannot fit the remaining page/turn budget')
+ }
+ this.state.spentTokens += cost
+ }
}
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 c0c8ac8c9..cbfa5cc58 100644
--- a/mcp-host/src/core/tools/__tests__/attachmentRead.budget.test.ts
+++ b/mcp-host/src/core/tools/__tests__/attachmentRead.budget.test.ts
@@ -315,9 +315,14 @@ describe('C16 small context windows under the production tool-message measuremen
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.
+ // Every emitted message is charged. Pages stay inside the turn; only
+ // notices may overdraw it, and never past half a turn more.
expect(ledger.snapshot().spentTokens).toBeGreaterThan(before)
- expect(ledger.snapshot().spentTokens).toBeLessThanOrEqual(turnTokens)
+ if (body.kind === 'text')
+ expect(ledger.snapshot().spentTokens).toBeLessThanOrEqual(turnTokens)
+ expect(ledger.snapshot().spentTokens).toBeLessThanOrEqual(
+ turnTokens + Math.floor(turnTokens / 2)
+ )
} catch (error) {
stop = error
}
@@ -330,6 +335,108 @@ describe('C16 small context windows under the production tool-message measuremen
expect(String(stop)).toMatch(/notice cannot fit/)
})
+ describe('bounded notice overdraft (jozer-rami M1)', () => {
+ const LARGE_WINDOW = 128_000
+
+ it('answers the read after the cap with a notice instead of failing the turn', async () => {
+ const id = randomUUID()
+ const [file] = admitted([rawFile(id, 'big.txt', 'text/plain', Buffer.alloc(3_000_000, 'q'))])
+ const { tool, ledger } = toolFor([file!], { windowTokens: LARGE_WINDOW })
+ const { turnTokens } = attachmentReadBudgets(LARGE_WINDOW)
+
+ const kinds: string[] = []
+ const bytesAfter: number[] = []
+ let offset = 0
+ for (let call = 0; call < 34; call++) {
+ const { body } = await runMeasured(tool, { attachmentId: id, offset })
+ kinds.push(body.kind as string)
+ bytesAfter.push(ledger.snapshot().bytesRead)
+ if (body.kind === 'text') offset += (body.byteRange as { length: number }).length
+ }
+ // Liveness: the turn really read pages before the budget bound.
+ expect(kinds[0]).toBe('text')
+ expect(bytesAfter[0]).toBeGreaterThan(0)
+ // Calls 33 and 34 are past the 32-read cap: both are notices.
+ expect(kinds[32]).toBe('read_budget_exhausted')
+ expect(kinds[33]).toBe('read_budget_exhausted')
+ const firstNotice = kinds.indexOf('read_budget_exhausted')
+ expect(kinds.slice(firstNotice).every(kind => kind === 'read_budget_exhausted')).toBe(true)
+ // A notice reads nothing.
+ expect(bytesAfter[33]).toBe(bytesAfter[32])
+ expect(bytesAfter[32]).toBe(bytesAfter[firstNotice])
+ expect(ledger.snapshot().reads).toBe(32)
+ expect(ledger.snapshot().spentTokens).toBeLessThanOrEqual(
+ turnTokens + Math.floor(turnTokens / 2)
+ )
+ })
+
+ it('answers a cold-restored exhausted ledger with a notice', async () => {
+ const id = randomUUID()
+ const [file] = admitted([rawFile(id, 'cold.txt', 'text/plain', Buffer.from('cold page'))])
+ // Witness: the same read on a fresh ledger returns the text.
+ const fresh = await runMeasured(toolFor([file!], { windowTokens: LARGE_WINDOW }).tool, {
+ attachmentId: id,
+ })
+ expect(fresh.body.kind).toBe('text')
+
+ const ledger = new AttachmentReadLedger()
+ ledger.exhaust(LARGE_WINDOW)
+ const { tool } = toolFor([file!], { windowTokens: LARGE_WINDOW, ledger })
+ const { body, finalized } = await runMeasured(tool, { attachmentId: id })
+ expect(body.kind).toBe('read_budget_exhausted')
+ expect(finalized.is_error).toBe(false)
+ expect(finalized.content).not.toContain('cold page')
+ expect(ledger.snapshot().bytesRead).toBe(0)
+ })
+
+ it('answers an unavailable-bytes read on a spent turn with a notice', async () => {
+ const id = randomUUID()
+ const [file] = admitted([rawFile(id, 'gone.txt', 'text/plain', Buffer.from('gone'))])
+ const withoutBytes = { ...file!, dataBase64: undefined } as unknown as Attachment
+ const { turnTokens } = attachmentReadBudgets(LARGE_WINDOW)
+ // Witness: with budget left, the same attachment reports the missing bytes.
+ const fresh = await runMeasured(
+ toolFor([withoutBytes], { windowTokens: LARGE_WINDOW }).tool,
+ { attachmentId: id }
+ )
+ expect(fresh.body.reason).toBe('bytes_unavailable_after_restart')
+
+ const ledger = new AttachmentReadLedger()
+ ledger.restore({ reads: 5, spentTokens: turnTokens, bytesRead: 0 })
+ const { tool } = toolFor([withoutBytes], { windowTokens: LARGE_WINDOW, ledger })
+ const { body } = await runMeasured(tool, { attachmentId: id })
+ expect(body.kind).toBe('read_budget_exhausted')
+ expect(ledger.snapshot().spentTokens).toBeGreaterThan(turnTokens)
+ })
+
+ it('still stops the turn once notices would pass half a turn of overdraft', async () => {
+ const id = randomUUID()
+ const [file] = admitted([rawFile(id, 'stop.txt', 'text/plain', Buffer.from('stop page'))])
+ const ledger = new AttachmentReadLedger()
+ ledger.exhaust(LARGE_WINDOW)
+ const { tool } = toolFor([file!], { windowTokens: LARGE_WINDOW, ledger })
+ const { turnTokens } = attachmentReadBudgets(LARGE_WINDOW)
+
+ let notices = 0
+ let stop: unknown = null
+ for (let call = 0; call < 5_000 && stop === null; call++) {
+ try {
+ const { body } = await runMeasured(tool, { attachmentId: id })
+ expect(body.kind).toBe('read_budget_exhausted')
+ notices += 1
+ } catch (error) {
+ stop = error
+ }
+ }
+ expect(notices).toBeGreaterThanOrEqual(2)
+ expect(String(stop)).toMatch(/notice cannot fit/)
+ expect(ledger.snapshot().spentTokens).toBeLessThanOrEqual(
+ turnTokens + Math.floor(turnTokens / 2)
+ )
+ expect(ledger.snapshot().bytesRead).toBe(0)
+ })
+ })
+
it('keeps error and binary results no larger than the exhausted notice (regression guard)', async () => {
const textId = randomUUID()
const binaryId = randomUUID()
@@ -379,18 +486,37 @@ describe('C16 finalize fence', () => {
expect(ledger.snapshot().bytesRead).toBe(0)
})
- it('fails closed when even the trusted notice cannot fit the remaining budget', async () => {
+ it('answers with the trusted notice from the overdraft when the turn has no room left', async () => {
const [file] = admitted([
rawFile('file-tight', 'tight.txt', 'text/plain', Buffer.from('tight page body')),
])
const ledger = new AttachmentReadLedger()
- const spent = Math.floor(WINDOW_TOKENS * 0.3) - 1
- ledger.restore({ reads: 1, spentTokens: spent, bytesRead: 0 })
+ const turnTokens = Math.floor(WINDOW_TOKENS * 0.3)
+ ledger.restore({ reads: 1, spentTokens: turnTokens - 1, bytesRead: 0 })
const { tool } = toolFor([file!], { ledger })
- await expect(runRead(tool, { attachmentId: 'file-tight' })).rejects.toThrow(
- /cannot fit|budget/i
- )
+ const { finalized } = await runRead(tool, { attachmentId: 'file-tight' })
+ const body = JSON.parse(finalized.rawContent as string) as Record<string, unknown>
+ expect(body.kind).toBe('read_budget_exhausted')
+ expect(finalized.content).not.toContain('tight page body')
+ expect(ledger.snapshot().bytesRead).toBe(0)
+ expect(ledger.snapshot().spentTokens).toBeGreaterThan(turnTokens)
+ })
+
+ it('fails closed when the notice would pass half a turn of overdraft', async () => {
+ const [file] = admitted([
+ rawFile('file-over', 'over.txt', 'text/plain', Buffer.from('over page body')),
+ ])
+ const ledger = new AttachmentReadLedger()
+ const turnTokens = Math.floor(WINDOW_TOKENS * 0.3)
+ ledger.restore({
+ reads: 1,
+ spentTokens: turnTokens + Math.floor(turnTokens / 2) - 1,
+ bytesRead: 0,
+ })
+ const { tool } = toolFor([file!], { ledger })
+
+ await expect(runRead(tool, { attachmentId: 'file-over' })).rejects.toThrow(/notice cannot fit/)
})
it('finalizes exactly once without another tool execution', async () => {
diff --git a/mcp-host/src/core/tools/attachmentRead.ts b/mcp-host/src/core/tools/attachmentRead.ts
index 43a7e4f4f..1611b26a9 100644
--- a/mcp-host/src/core/tools/attachmentRead.ts
+++ b/mcp-host/src/core/tools/attachmentRead.ts
@@ -364,8 +364,10 @@ export class AttachmentReadTool implements Tool {
/**
* Final budget fence. Runs once per executed read after safety, spillover
* and any result transform. If the final message outgrew the reservation,
- * replace it with the trusted exhausted notice at the ORIGINAL offset; if
- * even that cannot fit, throw so publication stops without a rerun.
+ * replace it with the trusted exhausted notice at the ORIGINAL offset. A
+ * notice that no longer fits the turn is charged to the bounded notice
+ * overdraft; once that is spent too, throw so publication stops without a
+ * rerun.
*/
finalizeResult(result: ToolResult, context: ToolEmissionContext): ToolResult {
const pending = this.pending
@@ -387,10 +389,12 @@ export class AttachmentReadTool implements Tool {
)
const noticeContent = context.renderContent(noticeRaw)
const noticeCost = context.measureContent(noticeContent)
- if (!this.ledger.canEmit(this.contextWindowTokens, noticeCost)) {
- throw new Error('Attachment read notice cannot fit the remaining page/turn budget')
+ if (this.ledger.canEmit(this.contextWindowTokens, noticeCost)) {
+ this.ledger.debit(this.contextWindowTokens, noticeCost, 0)
+ } else {
+ // Throws once the notice overdraft is spent, which stops the turn.
+ this.ledger.debitNotice(this.contextWindowTokens, noticeCost)
}
- this.ledger.debit(this.contextWindowTokens, noticeCost, 0)
return {
...result,
content: noticeContent,