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.jsonindex 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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 += costthis.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.tsindex 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 measuremenconst { 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 measuremenexpect(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.tsindex 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,