Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { createHash } from 'node:crypto'
import type { Conversation, Turn } from '../core/types'
import { getDisplayName } from '../progress/intentExtraction'
import type { ContextBreakdownWire, SessionTokensWire, TurnToolStepWire } from './types'
// Wire projections: map a Conversation / Turn to the runtime API shapes served
// by `/v1/runtime/sessions` and `/messages` (per-session + per-turn token
// usage, and per-turn tool steps). Pure functions, unit-tested in isolation.
type SessionTokenSource = Pick<
Conversation,
| 'input_tokens'
| 'output_tokens'
| 'cache_read_tokens'
| 'cache_write_tokens'
| 'cacheTokensReported'
>
export interface SessionsCursor {
version: 1
scope: string
updatedAt: string
key: string
}
function isCanonicalIsoTimestamp(value: string): boolean {
const milliseconds = Date.parse(value)
return Number.isFinite(milliseconds) && new Date(milliseconds).toISOString() === value
}
export function sessionsCursorScope(userSub: string, agent?: string): string {
return createHash('sha256')
.update(JSON.stringify([userSub, agent ?? null]))
.digest('base64url')
.slice(0, 24)
}
export function decodeSessionsCursor(
cursor: string | undefined,
expectedScope?: string
): SessionsCursor | null {
if (!cursor) return null
try {
const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')) as {
version?: unknown
scope?: unknown
updatedAt?: unknown
key?: unknown
}
if (
parsed.version !== 1 ||
typeof parsed.scope !== 'string' ||
parsed.scope.length === 0 ||
(expectedScope !== undefined && parsed.scope !== expectedScope) ||
typeof parsed.updatedAt !== 'string' ||
typeof parsed.key !== 'string' ||
parsed.key.length === 0 ||
!isCanonicalIsoTimestamp(parsed.updatedAt)
) {
return null
}
return {
version: 1,
scope: parsed.scope,
updatedAt: parsed.updatedAt,
key: parsed.key,
}
} catch {
return null
}
}
export function encodeSessionsCursor(updatedAt: string, key: string, scope = 'unscoped'): string {
return Buffer.from(JSON.stringify({ version: 1, scope, updatedAt, key }), 'utf8').toString(
'base64url'
)
}
export function paginateSessionSummaries<T extends { key: string; lastActivityAt: Date }>(
entries: T[],
limit: number | undefined,
encodeKey: (key: string) => string = key => key,
cursorScope = 'unscoped'
): { page: T[]; nextCursor?: string } {
if (limit === undefined) return { page: entries }
const page = entries.slice(0, limit)
const last = page.at(-1)
return {
page,
...(entries.length > page.length && last
? {
nextCursor: encodeSessionsCursor(
last.lastActivityAt.toISOString(),
encodeKey(last.key),
cursorScope
),
}
: {}),
}
}
export function projectMessageWindowBounds(
turns: Array<{ number: number }>,
bounds: { firstTurnNumber?: number; lastTurnNumber?: number },
_query: { beforeTurn?: number; afterTurn?: number }
) {
const oldestTurnNumber = turns[0]?.number
const latestTurnNumber = turns.at(-1)?.number
return {
oldestTurnNumber,
latestTurnNumber,
hasMoreBefore:
bounds.firstTurnNumber !== undefined &&
oldestTurnNumber !== undefined &&
oldestTurnNumber > bounds.firstTurnNumber,
hasMoreAfter:
bounds.lastTurnNumber !== undefined &&
latestTurnNumber !== undefined &&
latestTurnNumber < bounds.lastTurnNumber,
}
}
/**
* Project a Conversation's lifetime token mirror into the wire shape served by
* `/v1/runtime/sessions` and `/messages`.
*
* Returns `undefined` when the session has had no LLM call yet, so the desktop
* shows no counter. `cacheRead`/`cacheWrite` are included ONLY when the model
* reported cache info (`cacheTokensReported`) — distinguishing "0 because no
* cache hit" (Anthropic) from "absent because the provider doesn't report
* cache" (OpenAI / zai / bailian).
*/
export function projectSessionTokens(
conversation: SessionTokenSource
): SessionTokensWire | undefined {
const hasTokens =
!!conversation.input_tokens ||
!!conversation.output_tokens ||
!!conversation.cache_read_tokens ||
!!conversation.cache_write_tokens
if (!hasTokens) return undefined
return {
input: conversation.input_tokens ?? 0,
output: conversation.output_tokens ?? 0,
...(conversation.cacheTokensReported
? {
cacheRead: conversation.cache_read_tokens ?? 0,
cacheWrite: conversation.cache_write_tokens ?? 0,
}
: {}),
}
}
/**
* Project a Conversation's send-time context-window breakdown into the wire
* shape served on-demand by `/v1/runtime/sessions/:agent/:chatId/context-breakdown`.
*
* Returns `undefined` when the session has no snapshot yet (cold-load before
* the first turn). `fillRatio = totalInputTokens / maxTokens`. `cacheHitRate`
* is included ONLY when the model reported cache info (`cacheTokensReported`),
* computed from the SAME lifetime columns `projectSessionTokens` reads (#11) —
* no new columns. `cache_read / (cache_read + input)`.
*/
export function projectContextBreakdown(
conversation: Conversation
): ContextBreakdownWire | undefined {
const breakdown = conversation.contextBreakdown
if (!breakdown) return undefined
const fillRatio = breakdown.maxTokens > 0 ? breakdown.totalInputTokens / breakdown.maxTokens : 0
let cacheHitRate: number | undefined
if (conversation.cacheTokensReported) {
const cacheRead = conversation.cache_read_tokens ?? 0
const input = conversation.input_tokens ?? 0
const denom = cacheRead + input
// Omit cacheHitRate entirely when there's no usage yet (denom === 0):
// emitting 0 here would render a misleading "Average cache hit rate 0.0%".
if (denom > 0) cacheHitRate = cacheRead / denom
}
return {
buckets: { ...breakdown.buckets },
totalInputTokens: breakdown.totalInputTokens,
maxTokens: breakdown.maxTokens,
fillRatio,
...(cacheHitRate !== undefined ? { cacheHitRate } : {}),
capturedAtTurn: breakdown.capturedAtTurn,
}
}
/**
* Project one turn's token usage into the wire shape for `/messages`.
*
* Returns `undefined` for a turn with no recorded usage. Unlike the session
* projection (which carries a separate `cacheTokensReported` flag), the per-turn
* mirror preserves "unreported" faithfully: a defined `cache_*` field IS the
* "model reports cache" signal, so cacheRead/cacheWrite are included exactly
* when the turn has them defined (Anthropic's defined 0 included; OpenAI's
* undefined omitted).
*/
export function projectTurnTokens(turn: Turn): SessionTokensWire | undefined {
const hasTokens =
!!turn.input_tokens ||
!!turn.output_tokens ||
!!turn.cache_read_tokens ||
!!turn.cache_write_tokens
if (!hasTokens) return undefined
const cacheReported =
turn.cache_read_tokens !== undefined || turn.cache_write_tokens !== undefined
return {
input: turn.input_tokens ?? 0,
output: turn.output_tokens ?? 0,
...(cacheReported
? { cacheRead: turn.cache_read_tokens ?? 0, cacheWrite: turn.cache_write_tokens ?? 0 }
: {}),
}
}
/**
* Project a turn's tool calls to the minimal wire shape the desktop progress
* stepper needs (#582), so its "N tools" list survives a reload / cold-load (the
* live SSE steps are renderer-only). NEVER exposes raw arguments or tool output —
* only the server-derived `displayName`, the canonical tool name (already shown
* live), state, duration, and a redacted `errorSummary`.
*
* `redactError` MUST mirror the live SSE path's redaction (secret-scrub via
* `Safety.sanitizeOutput` + `sanitizeError` strip/truncate): the persisted
* `tc.error` (cold-loaded raw from `messages.content`, `reconstruct.ts`) is NOT
* sanitized at rest, so the boundary is enforced here. Required (not optional) so
* a caller can't accidentally ship the raw error. Returns `undefined` for a turn
* with no tool calls.
*/
export function projectTurnToolSteps(
turn: Turn,
redactError: (toolName: string, rawError: string) => string
): TurnToolStepWire[] | undefined {
if (!turn.tool_calls?.length) return undefined
return turn.tool_calls.map(tc => {
const summary = tc.error ? redactError(tc.name, tc.error) : ''
return {
toolName: tc.name,
displayName: getDisplayName(tc.name),
state: tc.error ? ('error' as const) : ('completed' as const),
...(tc.duration_ms != null ? { durationMs: tc.duration_ms } : {}),
...(summary ? { errorSummary: summary } : {}),
}
})
}