Skip to content

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

TypeScript

test: add liveness witnesses and cover admission, paging and wiring gaps

Alfredo Lopez39d92dcba4c4
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index b9a4efe43..0854ac125 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.450",
+ "version": "0.1.451",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.450",
+ "version": "0.1.451",
"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 696762c7a..133f9ab58 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.450",
+ "version": "0.1.451",
"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__/messageHandler.duplicate.test.ts b/mcp-host/src/__tests__/messageHandler.duplicate.test.ts
index 6caa875b5..69fdc4993 100644
--- a/mcp-host/src/__tests__/messageHandler.duplicate.test.ts
+++ b/mcp-host/src/__tests__/messageHandler.duplicate.test.ts
@@ -305,10 +305,12 @@ describe('IncomingMessageHandler — duplicate delivery keeps acceptedAttachment
const second = await new IncomingMessageHandler(message, deps).execute()
- // Witness: this is the replayed failure of the same task.
+ // Witnesses: this is the replayed failure of the same task, and its record
+ // holds the ids a success would have named.
expect(second.success).toBe(false)
expect(second.error?.code).toBe('LLM_INSUFFICIENT_QUOTA')
expect(second.taskId).toBe(task.id)
+ expect(deps.taskLifecycle.get(task.id)?.acceptedAttachmentIds).toEqual(['file-1', 'image-1'])
expect('acceptedAttachmentIds' in second).toBe(false)
})
@@ -412,6 +414,66 @@ describe('IncomingMessageHandler — duplicate delivery keeps acceptedFileRefere
await firstPromise
})
+ it('does not attach them to the replayed error of a FAILED task', async () => {
+ const deps = createMockDeps()
+ const message = resolvedMessage('msg-ref-failed')
+ const first = new IncomingMessageHandler(message, deps)
+ const firstPromise = first.execute()
+ await new Promise(r => setTimeout(r, 10))
+ const task = deps.messageQueue.dequeue()!
+ deps.messageQueue.failTask(task, {
+ code: 'LLM_INSUFFICIENT_QUOTA',
+ message: 'out of credit',
+ retryable: false,
+ provider: 'openai',
+ })
+ await firstPromise
+
+ const second = await new IncomingMessageHandler(message, deps).execute()
+
+ // Witnesses: this is the replayed failure of the same task, and its record
+ // holds the ids a success would have named.
+ expect(second.success).toBe(false)
+ expect(second.error?.code).toBe('LLM_INSUFFICIENT_QUOTA')
+ expect(second.taskId).toBe(task.id)
+ expect(deps.taskLifecycle.get(task.id)?.acceptedFileReferenceIds).toEqual([
+ available.id,
+ stale.id,
+ ])
+ expect('acceptedFileReferenceIds' in second).toBe(false)
+ })
+
+ it('logs a missing lifecycle record and replays the outcome without ids', async () => {
+ const deps = createMockDeps()
+ const message = resolvedMessage('msg-ref-record-missing')
+ const first = new IncomingMessageHandler(message, deps)
+ first.executeAsync()
+ const task = deps.messageQueue.dequeue()!
+ task.result = { response: 'first answer', model: 'test-model' }
+ deps.messageQueue.completeTask(task)
+ await task.responseCallback!({ response: 'first answer' })
+
+ const warn = vi.spyOn(logger, 'warn')
+ const get = vi.spyOn(deps.taskLifecycle, 'get').mockReturnValue(null)
+ const second = new IncomingMessageHandler(message, deps).executeAsync()
+
+ // Witnesses: the duplicate replayed the completed task, and the missing
+ // record was logged.
+ expect(second).toMatchObject({ success: true, status: 'completed', taskId: task.id })
+ expect(warn).toHaveBeenCalledWith(
+ {
+ event: 'duplicate_delivery_record_missing',
+ taskId: expect.any(String),
+ priorTaskId: task.id,
+ priorStatus: 'completed',
+ },
+ 'Duplicate delivery record missing'
+ )
+ expect('acceptedFileReferenceIds' in second).toBe(false)
+ get.mockRestore()
+ warn.mockRestore()
+ })
+
it('records only resolutions, never the raw references a caller sent', async () => {
const deps = createMockDeps()
const message: IncomingMessage = {
@@ -427,6 +489,13 @@ describe('IncomingMessageHandler — duplicate delivery keeps acceptedFileRefere
const second = new IncomingMessageHandler(message, deps).executeAsync()
+ // Witness: a message the same Host resolved records its ids.
+ new IncomingMessageHandler(resolvedMessage('msg-ref-resolved'), deps).executeAsync()
+ const resolvedTask = deps.messageQueue.dequeue()!
+ expect(deps.taskLifecycle.get(resolvedTask.id)?.acceptedFileReferenceIds).toEqual([
+ available.id,
+ stale.id,
+ ])
// Witness: the duplicate replayed the completed outcome.
expect(second.status).toBe('completed')
expect(deps.taskLifecycle.get(task.id)?.acceptedFileReferenceIds).toEqual([])
diff --git a/mcp-host/src/agent/__tests__/attachmentRead.sqlite.integration.test.ts b/mcp-host/src/agent/__tests__/attachmentRead.sqlite.integration.test.ts
new file mode 100644
index 000000000..fc86bfee2
--- /dev/null
+++ b/mcp-host/src/agent/__tests__/attachmentRead.sqlite.integration.test.ts
@@ -0,0 +1,161 @@
+/**
+ * #666 — persistence boundary of `clerum__attachment_read`. A complete task
+ * runs through the real TaskExecutor, tool loop and native registry on a
+ * ConversationManager backed by the SQLite store. The final answer quotes the
+ * page text the tool returned; the attachment's `dataBase64` never reaches a
+ * row.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { createHash } from 'node:crypto'
+import { config as appConfig } from '../../config'
+import { ConversationManager } from '../../core/conversation/conversation'
+import { makeSqliteStore } from '../../core/conversation/persistence/__tests__/testHelpers'
+import { SimpleEventEmitter } from '../../core/orchestration/eventEmitter'
+import { type ChatMessage, FinishReason, type ToolCall } from '../../core/types'
+import { TaskLifecycle } from '../../lifecycle/taskLifecycle'
+import type { SingleTurnProvider } from '../../llm/types'
+import { McpManager } from '../../mcp/manager'
+import type { Task } from '../../queue/types'
+import { validateIncomingAttachments } from '../incomingAttachments'
+import { TaskExecutor, type TaskExecutorDeps } from '../taskExecutor'
+
+const SENTINEL = 'SENTINEL-666-sqlite-boundary'
+const usage = { input_tokens: 1, output_tokens: 1, total_tokens: 2 }
+
+function admittedFile(bytes: Buffer) {
+ const result = validateIncomingAttachments(
+ [
+ {
+ id: 'file-1',
+ 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-1' }
+ )
+ if (!result.ok) throw new Error(`fixture rejected: ${result.error.code}`)
+ return result.attachments![0]!
+}
+
+describe('clerum__attachment_read persistence boundary (#666)', () => {
+ const saved = {
+ enableApproval: appConfig.enableApproval,
+ dynamicToolsEnabled: appConfig.dynamicToolsEnabled,
+ }
+
+ afterEach(() => {
+ Object.assign(appConfig, saved)
+ })
+
+ it('persists the tool result without the attachment bytes', async () => {
+ Object.assign(appConfig, { enableApproval: false, dynamicToolsEnabled: false })
+ const attachment = admittedFile(Buffer.from(`Quarterly notes. ${SENTINEL}\n`))
+ const call: ToolCall = {
+ id: 'read-1',
+ name: 'clerum__attachment_read',
+ arguments: { attachmentId: 'file-1' },
+ }
+ let providerCalls = 0
+ const provider: SingleTurnProvider = {
+ getProviderType: () => 'openai',
+ classifyError: () => {
+ throw new Error('Unexpected provider failure')
+ },
+ completeSingleTurn: async () => {
+ throw new Error('Unexpected non-tool completion')
+ },
+ completeSingleTurnWithTools: async (messages: ChatMessage[]) => {
+ providerCalls += 1
+ if (providerCalls === 1)
+ return { content: null, tool_calls: [call], usage, finish_reason: FinishReason.ToolUse }
+ const result = messages.find(m => m.role === 'tool' && m.tool_call_id === call.id)
+ return {
+ content: `The tool returned: ${result?.content ?? 'nothing'}`,
+ tool_calls: null,
+ usage,
+ finish_reason: FinishReason.Stop,
+ }
+ },
+ }
+ const handle = makeSqliteStore()
+ try {
+ const task: Task = {
+ id: 'attachment-read-sqlite',
+ source: 'channel',
+ status: 'pending',
+ priority: 'normal',
+ createdAt: new Date(),
+ sourceMessage: {
+ sender: 'authenticated-user',
+ content: 'Analyze the attached file',
+ channelType: 'rpc',
+ channelId: 'isolated-channel',
+ messageId: 'message-1',
+ timestamp: new Date().toISOString(),
+ hostRef: 'fixture-host',
+ attachments: [attachment],
+ },
+ conversationHistory: [
+ { role: 'user', content: 'Analyze the attached file', timestamp: new Date() },
+ ],
+ responseCallback: vi.fn(async () => {}),
+ }
+ const lifecycle = new TaskLifecycle()
+ lifecycle.register(task)
+ const deps: TaskExecutorDeps = {
+ conversationManager: new ConversationManager(handle.store),
+ llmProvider: provider,
+ mcpManager: new McpManager(),
+ workspaceService: undefined,
+ modelName: 'test-model',
+ approvalConfig: undefined,
+ config: {
+ maxTaskDuration: 300000,
+ maxToolCallsPerTask: 10,
+ autoStart: true,
+ taskDelay: 0,
+ approvalTimeout: 300000,
+ },
+ coreEvents: new SimpleEventEmitter(),
+ cronScheduler: null,
+ taskLifecycle: lifecycle,
+ onApprovalNeeded: vi.fn(),
+ onComplete: vi.fn(),
+ onFail: vi.fn(),
+ dynamicEnvProvider: () => ({}),
+ }
+ const executor = new TaskExecutor(task, deps)
+ await executor.run()
+ await handle.persistQueue.drain()
+
+ expect(deps.onFail).not.toHaveBeenCalled()
+ expect(executor.executorState).toBe('completed')
+ const db = handle.worker.db
+ const tables = db
+ .prepare("SELECT name FROM sqlite_master WHERE type = 'table'")
+ .all() as Array<{ name: string }>
+ const rows = tables.flatMap(({ name }) =>
+ (db.prepare(`SELECT * FROM "${name}"`).all() as unknown[]).map(row => JSON.stringify(row))
+ )
+ // The task path persists the user message and the final answer, not
+ // tool rows. Witness: the persisted answer quotes the tool result, so
+ // the page and its reference reached a row.
+ const answerRows = db
+ .prepare("SELECT content FROM messages WHERE role = 'assistant' AND content IS NOT NULL")
+ .all() as Array<{ content: string }>
+ expect(answerRows).toHaveLength(1)
+ expect(answerRows[0]!.content).toContain(attachment.fileReference!.id)
+ expect(answerRows[0]!.content).toContain(SENTINEL)
+ expect(rows.length).toBeGreaterThan(0)
+ expect(rows.filter(row => row.includes(attachment.dataBase64))).toEqual([])
+ } finally {
+ await handle.shutdown()
+ }
+ })
+})
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 ae5103404..f76e92c19 100644
--- a/mcp-host/src/core/tools/__tests__/nativeToolRegistry.attachmentRead.test.ts
+++ b/mcp-host/src/core/tools/__tests__/nativeToolRegistry.attachmentRead.test.ts
@@ -7,6 +7,7 @@ import { createHash } from 'node:crypto'
import { validateIncomingAttachments } from '../../../agent/incomingAttachments'
import type { IncomingMessage } from '../../../server'
import type { NativeToolConfig } from '../../interfaces'
+import { SpilloverStorage } from '../../spillover'
import type { Attachment } from '../../types'
import { NativeToolRegistry } from '../nativeToolRegistry'
@@ -19,6 +20,7 @@ const config: NativeToolConfig = {
envAllowlist: ['PATH'],
memoryMaxSize: 1048576,
attachmentTextReadMaxBytes: 262_144,
+ toolSpilloverThresholdBytes: 8192,
}
function attachments(kind: 'file' | 'image'): Attachment[] {
@@ -92,6 +94,14 @@ describe('NativeToolRegistry — clerum__attachment_read (#666)', () => {
['no attachments', message()],
['only image attachments', message(attachments('image'))],
])('does not register the tool with %s', (_label, source) => {
+ // Witness: the same config registers the tool once a file is attached.
+ const control = new NativeToolRegistry(
+ config,
+ 'conv-1',
+ undefined,
+ message(attachments('file'))
+ )
+ expect(toolNames(control)).toContain('clerum__attachment_read')
const registry = new NativeToolRegistry(config, 'conv-1', undefined, source)
// Witness: the registry was built and presents its always-on native tools.
expect(toolNames(registry)).toContain('file_read')
@@ -106,4 +116,44 @@ describe('NativeToolRegistry — clerum__attachment_read (#666)', () => {
() => new NativeToolRegistry(withoutLimit, 'conv-1', undefined, message(attachments('file')))
).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', () => {
+ const storage = new SpilloverStorage({
+ workspacePath: '/tmp',
+ thresholdBytes: 8192,
+ ttlMs: 60_000,
+ gcIntervalMs: 0,
+ })
+ const withSpillover = new NativeToolRegistry(
+ config,
+ 'conv-1',
+ undefined,
+ message(attachments('file')),
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ storage
+ )
+ expect(withSpillover.get('clerum__spillover_read')).not.toBeNull()
+ expect(withSpillover.get('clerum__attachment_read')!.description()).toContain(
+ 'spillover threshold (8192 bytes)'
+ )
+ 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')
+ })
})