Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* T1.5 — `clerum__spillover_read` native tool.
*
* When `executeSingleTool` decides a tool output is too large to ship inline,
* it writes the blob to `${WORKSPACE}/spillover/<task_id>/<tool_call_id>.json`
* and embeds a `SpilloverSummary` in the `tool` message. The agent calls
* this tool with `ref` (and optionally a `[start, end)` byte range) to fetch
* the full content on demand.
*
* Important: this tool itself NEVER spills its own output (exception §4.1 of
* the plan). It declares `spilloverExempt()`, which `executeSingleTool`
* honours; `SpilloverStorage.maybePersist` keeps a guard on the tool name as
* its own recursion invariant.
*/
import { Tool } from '../interfaces'
import { SpilloverStorage, clerumSpilloverReadsTotal } from '../spillover'
import { ToolOutput } from '../types'
export class SpilloverReadTool implements Tool {
constructor(private readonly storage: SpilloverStorage) {}
name(): string {
return 'clerum__spillover_read'
}
description(): string {
return (
'Fetch the full content (or a byte range) of a tool result that was ' +
'spilled to disk. Use the `spillover_ref` value from a previous tool ' +
'message whose `content` included a `spillover_ref` field. Optionally ' +
'pass a `range: { start, end }` to read a `[start, end)` byte window.'
)
}
parametersSchema(): Record<string, unknown> {
return {
type: 'object',
properties: {
ref: {
type: 'string',
description: 'The spillover URI: "spillover://<task_id>/<tool_call_id>.json".',
},
range: {
type: 'object',
description: 'Optional byte range [start, end). If omitted, returns the full content.',
properties: {
start: { type: 'integer', minimum: 0 },
end: { type: 'integer', minimum: 1 },
},
required: ['start', 'end'],
},
},
required: ['ref'],
}
}
requiresSanitization(): boolean {
// The blob can contain secrets the global sanitizer wants to redact;
// matches `file_read` which is sanitized for the same reason.
return true
}
requiresApproval(): boolean {
// The original tool already passed (or didn't need) approval. Reading
// back the persisted result is not a fresh side effect.
return false
}
spilloverExempt(): boolean {
// The model asked for the bytes of a blob that was spilled once;
// spilling them again would be recursion.
return true
}
async execute(params: Record<string, unknown>): Promise<ToolOutput> {
const start = Date.now()
const ref = typeof params.ref === 'string' ? (params.ref as string) : null
const rawRange = params.range
const range =
rawRange && typeof rawRange === 'object' && rawRange !== null
? (rawRange as { start?: unknown; end?: unknown })
: null
if (!ref) {
return {
content: 'Error: missing or invalid `ref` parameter.',
duration_ms: Date.now() - start,
is_error: true,
}
}
const blob = await this.storage.load(ref)
if (!blob) {
return {
content: `Error: spillover blob ${ref} not found or expired.`,
duration_ms: Date.now() - start,
is_error: true,
}
}
if (range !== null) {
const rangeStart = range.start
const rangeEnd = range.end
if (
typeof rangeStart !== 'number' ||
typeof rangeEnd !== 'number' ||
!Number.isInteger(rangeStart) ||
!Number.isInteger(rangeEnd) ||
rangeStart < 0 ||
rangeEnd <= rangeStart ||
rangeEnd > blob.byte_size
) {
clerumSpilloverReadsTotal?.inc({ with_range: 'true' })
return {
content: `Error: invalid range [${String(rangeStart)}, ${String(rangeEnd)}) for byte_size=${blob.byte_size}.`,
duration_ms: Date.now() - start,
is_error: true,
}
}
const slice = Buffer.from(blob.content, 'utf8')
.subarray(rangeStart, rangeEnd)
.toString('utf8')
clerumSpilloverReadsTotal?.inc({ with_range: 'true' })
return {
content: slice,
duration_ms: Date.now() - start,
is_error: false,
}
}
clerumSpilloverReadsTotal?.inc({ with_range: 'false' })
return {
content: blob.content,
duration_ms: Date.now() - start,
is_error: false,
}
}
}