Skip to content

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

TypeScript
6.1 KB
Raw Blame
export const MAX_ATTACHMENT_READS_PER_TURN = 32

export function attachmentReadBudgets(windowTokens: number): {
  pageTokens: number
  turnTokens: number
} {
  if (!Number.isSafeInteger(windowTokens) || windowTokens <= 0) {
    throw new Error('attachmentReadContextWindowTokens must be a positive safe integer')
  }
  return { pageTokens: Math.floor(windowTokens * 0.1), turnTokens: Math.floor(windowTokens * 0.3) }
}

export interface AttachmentReadLedgerSnapshot {
  reads: number
  spentTokens: number
  bytesRead: number
}

function boundedCount(value: number): boolean {
  return Number.isSafeInteger(value) && value >= 0
}

/**
 * Strict reader for a persisted ledger snapshot. Returns null (never a guess,
 * never a partial value) unless every field is a safe non-negative integer and
 * the read count is within the hard cap. The spend is deliberately NOT clamped
 * to a window: a ledger that spent above the current envelope must stay
 * above it, so widening the window later cannot restore spent allowance.
 */
export function readAttachmentReadLedgerSnapshot(
  value: unknown
): AttachmentReadLedgerSnapshot | null {
  if (typeof value !== 'object' || value === null || Array.isArray(value)) return null
  const record = value as Record<string, unknown>
  const { reads, spentTokens, bytesRead } = record
  if (!boundedCount(reads as number) || !boundedCount(spentTokens as number)) return null
  if (!boundedCount(bytesRead as number)) return null
  if ((reads as number) > MAX_ATTACHMENT_READS_PER_TURN) return null
  return {
    reads: reads as number,
    spentTokens: spentTokens as number,
    bytesRead: bytesRead as number,
  }
}

/**
 * Monotone per-field maximum. The warm resume path merges the persisted
 * snapshot into the live ledger with this, so a stale or replayed approval can
 * never decrease reads or spend the running turn already recorded.
 */
export function mergeAttachmentReadLedgerSnapshots(
  live: AttachmentReadLedgerSnapshot,
  persisted: AttachmentReadLedgerSnapshot
): AttachmentReadLedgerSnapshot {
  return {
    reads: Math.max(live.reads, persisted.reads),
    spentTokens: Math.max(live.spentTokens, persisted.spentTokens),
    bytesRead: Math.max(live.bytesRead, persisted.bytesRead),
  }
}

/** Owned by one turn; registry memoization does not determine its lifetime. */
export class AttachmentReadLedger {
  private state: AttachmentReadLedgerSnapshot = { reads: 0, spentTokens: 0, bytesRead: 0 }

  snapshot(): AttachmentReadLedgerSnapshot {
    return { ...this.state }
  }

  reset(): void {
    this.state = { reads: 0, spentTokens: 0, bytesRead: 0 }
  }

  restore(snapshot: AttachmentReadLedgerSnapshot): void {
    const parsed = readAttachmentReadLedgerSnapshot(snapshot)
    if (!parsed) throw new Error('Invalid attachment read ledger snapshot')
    this.state = parsed
  }

  /**
   * Fail-closed state for a turn whose spend cannot be trusted (a legacy or
   * corrupt snapshot). No further page can
   * be emitted, and no spend is guessed.
   */
  exhaust(windowTokens: number): void {
    const { turnTokens } = attachmentReadBudgets(windowTokens)
    this.state = {
      reads: MAX_ATTACHMENT_READS_PER_TURN,
      spentTokens: Math.max(this.state.spentTokens, turnTokens),
      bytesRead: this.state.bytesRead,
    }
  }

  beginRead(): boolean {
    if (this.state.reads >= MAX_ATTACHMENT_READS_PER_TURN) return false
    this.state.reads += 1
    return true
  }

  pageAllowance(windowTokens: number, noticeCost: number): number {
    if (!boundedCount(noticeCost) || noticeCost === 0) {
      throw new Error('Invalid attachment notice cost')
    }
    const limits = attachmentReadBudgets(windowTokens)
    // Leave one notice for every remaining call and the first exhausted call,
    // but never more than half of the turn: on a small window 33 notices would
    // exceed the whole turn and no page could ever be emitted. Once the
    // reserved notices are spent, the finalize fence stops the turn.
    const affordableNotices = Math.floor(Math.floor(limits.turnTokens / 2) / noticeCost)
    if (affordableNotices < 1) {
      throw new Error(
        `Attachment read context window of ${windowTokens} tokens is too small to reserve a ${noticeCost}-token budget notice`
      )
    }
    const reserve =
      Math.min(MAX_ATTACHMENT_READS_PER_TURN - this.state.reads + 1, affordableNotices) * noticeCost
    return Math.max(
      0,
      Math.min(limits.pageTokens, limits.turnTokens - this.state.spentTokens - reserve)
    )
  }

  canEmit(windowTokens: number, cost: number): boolean {
    if (!boundedCount(cost)) return false
    const limits = attachmentReadBudgets(windowTokens)
    return cost <= limits.pageTokens && cost <= limits.turnTokens - this.state.spentTokens
  }

  debit(windowTokens: number, cost: number, bytesRead: number): void {
    if (
      !boundedCount(bytesRead) ||
      !this.canEmit(windowTokens, cost) ||
      !Number.isSafeInteger(this.state.spentTokens + cost) ||
      !Number.isSafeInteger(this.state.bytesRead + bytesRead)
    ) {
      throw new Error('Attachment output cannot fit the remaining page/turn budget')
    }
    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 nothing is
   * charged and false tells the caller to stop the turn. An invalid cost, a
   * cost above one page or an unsafe spend still throws.
   */
  debitNotice(windowTokens: number, cost: number): boolean {
    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)
    ) {
      throw new Error('Attachment read notice cannot fit the remaining page/turn budget')
    }
    if (this.state.spentTokens + cost > ceiling) return false
    this.state.spentTokens += cost
    return true
  }
}