Skip to content

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

TypeScript
30.4 KB
Raw Blame
import type { ImageInputDecision } from '@clerum/llm-providers'
import { SingleTurnProvider } from '../../llm'
import {
  type ImageInputCapabilitySource,
  type ImageInputResolver,
  type ImageTransportOperation,
  decideImageInput,
  imageInputDenialMessage,
  imageInputRolesFor,
  isCanonicalBase64Shape,
  isImageAttachmentMime,
} from '../../llm/imageInput'
import {
  clerumPromptCacheInputTokens,
  clerumPromptCacheReadTokens,
  clerumPromptCacheWriteTokens,
} from '../../llm/promptCacheMetrics'
import { logger } from '../../logger'
import { LlmUsageEvent, UsageReporter, newRequestId } from '../../usage/usageReporter.js'
import { visualDimensionLimit } from '../../visualInput/deliveryLimits'
import { gfsImageParts, projectGfsMessages } from '../../visualInput/messageProjection'
import { type ImageInputCapability, VisualInputError } from '../../visualInput/policy'
import { hasGfsImageInput, hasUnknownImageGeometry } from '../../visualInput/requestPolicy'
import type { SessionTokenUsage } from '../conversation/conversationStore'
import { LlmError, LlmErrorCode } from '../errors'
import { LlmPort } from '../interfaces'
import type { SystemPromptParts } from '../reasoning/systemPrompt'
import { redactDiagnosticField } from '../redactDiagnostics.js'
import type { TokenCounter } from '../tokenizer/tokenCounter'
import {
  ChatMessage,
  CompletionRequest,
  CompletionResponse,
  MessageContentPart,
  MessageRole,
  ToolCompletionRequest,
  ToolCompletionResponse,
  UsageContext,
} from '../types'

/**
 * T2.2 fallback: when the provider does not implement the cache-aware path,
 * concat `parts.stable` + `parts.context` into a single system message and
 * prepend it to the request `messages`. The wire shape stays identical to the
 * legacy single-string path, so providers without explicit cache markers
 * (OpenAI / ZAI / Bailian) keep working unchanged.
 */
function prependConcatSystem(parts: SystemPromptParts, messages: ChatMessage[]): ChatMessage[] {
  const content = [parts.stable, parts.context].filter(s => s && s.length > 0).join('\n\n')
  if (!content) return messages
  return [{ role: 'system', content }, ...messages]
}

/**
 * An image part the adapter may forward: PNG/JPEG mime and canonical base64
 * string data. Line-wrapped, `data:`-prefixed, URL-safe or unpadded base64
 * fails.
 */
function isWellFormedImagePart(part: { mimeType: unknown; data: unknown }): boolean {
  return (
    isImageAttachmentMime(part.mimeType) &&
    typeof part.data === 'string' &&
    isCanonicalBase64Shape(part.data)
  )
}

export type AdapterStaticContext = {
  host_ref: string
  context_ref: string | null
  llm_secret_name: string | null
}

function errorField(value: unknown, field: string): string | null {
  if (!value || typeof value !== 'object') return null
  const record = value as Record<string, unknown>
  const fieldValue = record[field]
  if (typeof fieldValue !== 'string') return null
  const trimmed = fieldValue.trim()
  return trimmed ? redactDiagnosticField(trimmed).slice(0, 120) : null
}

function providerErrorDiagnostics(err: unknown): Record<string, string> {
  const fields: Record<string, string> = {}
  const name = errorField(err, 'name')
  const type = errorField(err, 'type')
  const code = errorField(err, 'code')
  const status =
    typeof (err as { status?: unknown })?.status === 'number'
      ? String((err as { status: number }).status)
      : null
  const cause = err instanceof Error ? err.cause : undefined
  const causeName = errorField(cause, 'name')
  const causeCode = errorField(cause, 'code')

  if (name) fields.name = name
  if (type) fields.type = type
  if (code) fields.code = code
  if (status) fields.status = status
  if (causeName) fields.causeName = causeName
  if (causeCode) fields.causeCode = causeCode

  return fields
}

/**
 * Adapts an existing provider (implementing SingleTurnProvider)
 * to the spec's LlmPort interface.
 *
 * If a UsageReporter and staticContext are supplied, every successful LLM
 * call also produces an LlmUsageEvent enqueued to the reporter — this is
 * the single chokepoint described in
 * `docs/plans/llm-token-usage-tracking-*.md`.
 */
export class LlmPortAdapter implements LlmPort {
  constructor(
    private readonly provider: SingleTurnProvider,
    private readonly model: string,
    private readonly providerName: string,
    private readonly usageReporter?: UsageReporter,
    private readonly staticContext?: AdapterStaticContext,
    private readonly defaultUsageContext?: UsageContext,
    /**
     * Provider-aware token counter (P.2). Optional for legacy callers and
     * tests; production code paths always pass one constructed via
     * `createTokenCounter`. When present, `recordUsage` forwards the
     * `input_tokens` so the next pre-flight count can use the authoritative
     * number (Hermes `update_from_response` pattern).
     */
    private readonly tokenCounter?: TokenCounter,
    /**
     * Optional sink to accumulate each call's tokens into the durable
     * per-session counters (`sessions.*_tokens`). Per-task; bound to the active
     * Conversation by `taskExecutor.buildLoopConfig` / `stateMachine` (compact).
     * Tests and legacy callers omit it (no-op). Independent of `usageReporter`:
     * session persistence does not require control-api to be wired.
     */
    private readonly onUsageRecorded?: (usage: SessionTokenUsage) => void,
    /**
     * Issue #654 — live-catalog lookup for the image-input capability of the
     * (provider, model) this adapter is about to send. Absent (dev, tests,
     * unwired host) means `unknown`: requests without images are byte-identical
     * to today, requests carrying an image fail closed before the SDK.
     */
    private readonly imageInputResolver?: ImageInputResolver
  ) {}

  /**
   * Exposes the counter to downstream consumers (`PressureContextManager`,
   * `compactConversation`, future prompt-cache breakpoints). Returns
   * `undefined` only in tests that intentionally omit it.
   */
  getTokenCounter(): TokenCounter {
    if (!this.tokenCounter) {
      throw new Error(
        '[LlmPortAdapter] getTokenCounter() called before a counter was injected — wiring bug'
      )
    }
    return this.tokenCounter
  }

  async getImageInputCapability(signal?: AbortSignal): Promise<ImageInputCapability> {
    if (signal?.aborted) throw new VisualInputError('cancelled')
    // GFS tool results enter the loop as user visual parts through completeWithTools.
    // This is read admission only; dispatch rechecks the actual method and pair.
    const decision = this.decideImageInputForAttempt('completeWithTools', ['user'])
    if (decision.state !== 'supported') return { status: decision.state }
    return {
      status: 'supported',
      provider: this.provider.getProviderType(),
      model: this.model,
      evidence: decision.evidence?.reference ?? 'live-catalog-row',
      deliveryLimits: this.provider.getVisualDeliveryLimits?.('completeWithTools') ?? null,
    }
  }

  async complete(request: CompletionRequest): Promise<CompletionResponse> {
    logger.info(
      {
        provider: this.providerName,
        model: this.model,
        messageCount: request.messages.length,
        cache: Boolean(request.systemPromptParts),
      },
      'LLM completion started'
    )
    // Excluded from the SDK-classification catch below on purpose: a denied
    // image must stay a typed, terminal LlmError instead of being reclassified
    // by `provider.classifyError` (which would make it retryable).
    const guardedMessages = this.prepareMessagesForImageInput(
      request.messages,
      this.dispatchMethodFor(request, false)
    )
    const requestId = newRequestId()
    try {
      const messages = this.fitGfsImages(request, this.providerMessages(guardedMessages))
      const response = await this.dispatchComplete({ ...request, messages })
      logger.info({ finishReason: response.finish_reason }, 'LLM completion finished')
      this.recordUsage(requestId, request.usageContext, response.usage)
      return response
    } catch (err) {
      this.handleProviderError(err)
    }
  }

  async completeWithTools(request: ToolCompletionRequest): Promise<ToolCompletionResponse> {
    logger.info(
      {
        provider: this.providerName,
        model: this.model,
        toolCount: request.tools.length,
        messageCount: request.messages.length,
        cache: Boolean(request.systemPromptParts),
      },
      'LLM tool completion started'
    )
    // Same exclusion as `complete`: deny BEFORE the try/catch that classifies
    // provider SDK errors.
    const guardedMessages = this.prepareMessagesForImageInput(
      request.messages,
      this.dispatchMethodFor(request, true)
    )
    const requestId = newRequestId()
    try {
      const messages = this.fitGfsImages(request, this.providerMessages(guardedMessages))
      const response = await this.dispatchCompleteWithTools(
        { ...request, messages },
        hasGfsImageInput(messages)
      )
      const toolCallCount = response.tool_calls?.length ?? 0
      logger.info(
        { finishReason: response.finish_reason, toolCallCount, usage: response.usage },
        'LLM tool completion finished'
      )
      this.recordUsage(requestId, request.usageContext, response.usage)
      return response
    } catch (err) {
      this.handleProviderError(err)
    }
  }

  /**
   * Preserve the historical content-deduplicated API-key view without changing
   * the loop's canonical messages. Each fallback adapter selects its own view;
   * source-binding transports retain all identities before hashing them.
   */
  private providerMessages(messages: ChatMessage[]): ChatMessage[] {
    if (
      this.provider.requiresImageSourceIdentity ||
      !messages.some(message => message.contentParts?.some(part => part.sourceIdentityOnly))
    ) {
      return messages
    }
    const imageKey = (part: { mimeType: string; data: string }) =>
      `${part.mimeType}\u0000${part.data}`
    const represented = new Set<string>()
    for (const message of messages) {
      for (const part of message.contentParts ?? []) {
        if (part.type === 'image' && !part.sourceIdentityOnly) represented.add(imageKey(part))
      }
    }
    return messages.flatMap(message => {
      if (!message.contentParts?.some(part => part.sourceIdentityOnly)) return [message]
      let restoredImage = false
      const selected = new Set(message.contentParts.filter(part => !part.sourceIdentityOnly))
      for (const part of message.contentParts) {
        if (part.type !== 'image' || !part.sourceIdentityOnly || represented.has(imageKey(part)))
          continue
        // In a mixed chain, pruning can remove the older legacy representative.
        // Retain one current frame rather than silently losing all visual input.
        selected.add(part)
        represented.add(imageKey(part))
        restoredImage = true
      }
      if (restoredImage) {
        for (const part of message.contentParts) if (part.type === 'text') selected.add(part)
      }
      const contentParts = message.contentParts
        .filter(part => selected.has(part))
        .map(part => {
          if (!part.sourceIdentityOnly) return part
          const visible = { ...part }
          delete visible.sourceIdentityOnly
          return visible
        })
      return contentParts.length ? [{ ...message, contentParts }] : []
    })
  }

  private fitGfsImages(
    request: CompletionRequest | ToolCompletionRequest,
    providerMessages: ChatMessage[]
  ): ChatMessage[] {
    let messages = providerMessages
    const candidates = gfsImageParts(messages)
    if (candidates.length === 0) return messages

    const limits =
      this.provider.getVisualDeliveryLimits?.(
        this.dispatchMethodFor(request, 'tools' in request)
      ) ?? null
    const allImages = (current: ChatMessage[]) =>
      current.flatMap(message =>
        (message.contentParts ?? []).filter(
          (part): part is Extract<MessageContentPart, { type: 'image' }> =>
            part.type === 'image' && !part.sourceIdentityOnly
        )
      )
    const imageBytes = (part: Extract<MessageContentPart, { type: 'image' }>): number =>
      Buffer.byteLength(part.data, 'base64')
    if (!limits) {
      // A catalog vision capability does not establish a physical byte/count
      // contract. Keep the governed file receipt for this attempt, without pixels.
      return projectGfsMessages(
        messages,
        new Set(candidates),
        'provider_visual_profile_unavailable'
      )
    }
    if (hasUnknownImageGeometry(messages, limits)) {
      return projectGfsMessages(messages, new Set(candidates), 'geometry_unknown')
    }
    const exceeds = (current: ChatMessage[]): boolean => {
      const images = allImages(current)
      const dimensionLimit = visualDimensionLimit(limits, images.length)
      const totalImageBytes = images.reduce((total, part) => total + imageBytes(part), 0)
      const requestBytes = current.reduce(
        (total, message) => total + Buffer.byteLength(JSON.stringify(message), 'utf8'),
        'tools' in request ? Buffer.byteLength(JSON.stringify(request.tools ?? []), 'utf8') : 0
      )
      return (
        images.length > limits.maxImages ||
        (limits.maxTotalImageBytes !== undefined && totalImageBytes > limits.maxTotalImageBytes) ||
        (limits.maxImageBytes !== undefined &&
          images.some(part => imageBytes(part) > limits.maxImageBytes!)) ||
        (limits.maxImageEncodedBytes !== undefined &&
          images.some(part => part.data.length > limits.maxImageEncodedBytes!)) ||
        images.some(
          part =>
            part.width !== undefined &&
            part.height !== undefined &&
            ((dimensionLimit !== undefined &&
              (part.width > dimensionLimit || part.height > dimensionLimit)) ||
              (limits.maxPixels !== undefined && part.width * part.height > limits.maxPixels))
        ) ||
        requestBytes > limits.maxVisualRequestBytes
      )
    }

    let demoted = 0
    for (;;) {
      if (!exceeds(messages)) {
        if (demoted > 0)
          logger.info(
            { provider: this.providerName, model: this.model, demotedImages: demoted },
            'GFS images projected to references for this provider attempt'
          )
        return messages
      }
      const selected = candidates.pop()
      if (!selected) throw new VisualInputError('limit_exceeded')
      messages = projectGfsMessages(messages, new Set([selected]), 'image_input_limit_exceeded')
      demoted++
    }
  }

  /** Native cache markers when supported, otherwise the existing system-text projection. */
  private async dispatchComplete(request: CompletionRequest): Promise<CompletionResponse> {
    const parts = request.systemPromptParts
    if (
      this.dispatchMethodFor(request, false) === 'completeAndCache' &&
      parts &&
      this.provider.completeSingleTurnAndCache
    ) {
      return this.provider.completeSingleTurnAndCache(parts, request.messages, {
        max_tokens: request.max_tokens,
        temperature: request.temperature,
        signal: request.signal,
      })
    }
    const messages = parts ? prependConcatSystem(parts, request.messages) : request.messages
    return this.provider.completeSingleTurn(messages, {
      max_tokens: request.max_tokens,
      temperature: request.temperature,
      signal: request.signal,
    })
  }

  private async dispatchCompleteWithTools(
    request: ToolCompletionRequest,
    verificationRequired: boolean
  ): Promise<ToolCompletionResponse> {
    const parts = request.systemPromptParts
    if (
      this.dispatchMethodFor(request, true) === 'completeWithToolsAndCache' &&
      parts &&
      this.provider.completeSingleTurnWithToolsAndCache
    ) {
      return this.provider.completeSingleTurnWithToolsAndCache(
        parts,
        request.messages,
        request.tools,
        {
          max_tokens: request.max_tokens,
          temperature: request.temperature,
          tool_choice: request.tool_choice,
          signal: request.signal,
          ...(verificationRequired ? { verifyImageInput: true } : {}),
        }
      )
    }
    const messages = parts ? prependConcatSystem(parts, request.messages) : request.messages
    return this.provider.completeSingleTurnWithTools(messages, request.tools, {
      max_tokens: request.max_tokens,
      temperature: request.temperature,
      tool_choice: request.tool_choice,
      signal: request.signal,
      ...(verificationRequired ? { verifyImageInput: true } : {}),
    })
  }

  /**
   * Issue #654 — the single source of truth for which transport implementation
   * a request will actually use. `dispatchComplete`/`dispatchCompleteWithTools`
   * branch on this same method, so the image guard can never evaluate a
   * different path than the one that runs.
   */
  private dispatchMethodFor(
    request: { systemPromptParts?: SystemPromptParts },
    withTools: boolean
  ): ImageTransportOperation {
    const parts = request.systemPromptParts
    if (withTools) {
      return parts && this.provider.completeSingleTurnWithToolsAndCache
        ? 'completeWithToolsAndCache'
        : 'completeWithTools'
    }
    return parts && this.provider.completeSingleTurnAndCache ? 'completeAndCache' : 'complete'
  }

  /**
   * Resolve the image decision for this physical attempt. Returns `unknown`
   * when no catalog resolver is wired or the pair is absent from it — an
   * absent catalog entry is never an implicit allow.
   */
  private decideImageInputForAttempt(
    method: ImageTransportOperation,
    roles: readonly MessageRole[]
  ): ImageInputDecision {
    if (!this.imageInputResolver) return { state: 'unknown', reason: 'model_unknown' }
    const providerType = this.provider.getProviderType()
    let source: ImageInputCapabilitySource | undefined
    try {
      source = this.imageInputResolver(providerType, this.model)
    } catch (err) {
      // A catalog read failure must not fail a text-only turn, and must not be
      // read as support: it degrades to `unknown`, which blocks images only.
      logger.warn(
        {
          component: 'LlmPortAdapter',
          provider: this.providerName,
          model: this.model,
          err,
        },
        'image-input capability resolver threw; treating as unknown'
      )
      source = undefined
    }
    if (!source) return { state: 'unknown', reason: 'model_unknown' }
    return decideImageInput({
      providerType,
      method,
      roles,
      capability: source.capability,
    })
  }

  /**
   * Fail closed when this attempt carries a USER image and the intersection of
   * model evidence, transport implementation and role is not
   * affirmative. Text-only requests return immediately (no resolver call).
   *
   * #654 — images the agent's own tools produced are withheld rather than
   * fatal: the turn is dispatched without them and `content` records how many
   * were dropped and why. A model with no image evidence must still be able to
   * finish a text task that happens to call a screenshot tool; refusing there
   * would turn a capability gap into a task failure the user never asked for.
   *
   * Encoding is validated before any capability decision. A malformed USER
   * image (mime other than PNG/JPEG, non-string data, or data that is not
   * canonical base64) is a terminal `InvalidAttachment`. A malformed image in a
   * `tool_result` message came from an external MCP server, not the user, so it
   * is removed instead: the message keeps its other parts and `content` records
   * how many were dropped for invalid encoding. It is never forwarded, even to
   * an image-capable model. A message left with no image part stops being an
   * image carrier; valid tool images continue through the capability decision.
   *
   * Returns the message array to dispatch. The input array is never mutated,
   * so a later failover attempt on a supported pair still sees the images.
   */
  private prepareMessagesForImageInput(
    input: ChatMessage[],
    method: ImageTransportOperation
  ): ChatMessage[] {
    const messages = this.removeMalformedToolImages(input, method)
    for (const message of messages) {
      if (message.contentParts === undefined) continue
      if (
        !Array.isArray(message.contentParts) ||
        message.contentParts.some(
          part =>
            !part ||
            (part.type !== 'text' && part.type !== 'image') ||
            (part.type === 'image' && !isWellFormedImagePart(part))
        )
      ) {
        throw new LlmError(
          'The request contains an unsupported image format or encoding.',
          this.providerName,
          LlmErrorCode.InvalidAttachment,
          false
        )
      }
    }
    const roles = imageInputRolesFor(messages)
    if (roles.length === 0) return messages
    const decision = this.decideImageInputForAttempt(method, roles)
    if (decision.state === 'supported') {
      const gfsImages = gfsImageParts(messages)
      if (gfsImages.length > 0) {
        const limits = this.provider.getVisualDeliveryLimits?.(method) ?? null
        // Project receipts while their GFS identities are still present. The
        // API-key view may later deduplicate a frame against an ordinary image.
        if (!limits)
          return projectGfsMessages(
            messages,
            new Set(gfsImages),
            'provider_visual_profile_unavailable'
          )
        if (hasUnknownImageGeometry(messages, limits))
          return projectGfsMessages(messages, new Set(gfsImages), 'geometry_unknown')
      }
      return messages
    }

    const carriesImages = (message: ChatMessage): boolean =>
      message.contentParts?.some(part => part.type === 'image') === true
    const userImages = messages.some(
      message => carriesImages(message) && message.imageOrigin !== 'tool_result'
    )
    if (userImages) {
      logger.warn(
        {
          component: 'LlmPortAdapter',
          provider: this.providerName,
          model: this.model,
          method,
          roles,
          reason: decision.reason,
          validUntil: decision.validUntil,
        },
        'image input denied before provider dispatch'
      )
      throw new LlmError(
        imageInputDenialMessage(decision, { provider: this.providerName, model: this.model }),
        this.providerName,
        decision.state === 'unsupported'
          ? LlmErrorCode.ImageInputUnsupported
          : LlmErrorCode.ImageInputUnknown,
        false
      )
    }

    const gfsImages = gfsImageParts(messages)
    const projected = projectGfsMessages(
      messages,
      new Set(gfsImages),
      'model_image_input_unavailable'
    )
    const withheld = projected.filter(
      message => message.imageOrigin === 'tool_result' && carriesImages(message)
    )
    if (withheld.length === 0) return projected
    const count = withheld.reduce(
      (total, message) =>
        total + message.contentParts!.filter(part => part.type === 'image').length,
      0
    )
    logger.warn(
      {
        component: 'LlmPortAdapter',
        provider: this.providerName,
        model: this.model,
        method,
        reason: decision.reason,
        withheldImages: count,
      },
      'tool screenshots withheld: model has no affirmative image-input evidence'
    )
    const notice = `[${count} screenshot(s) returned by tool results were not forwarded: ${imageInputDenialMessage(
      decision,
      { provider: this.providerName, model: this.model }
    )}]`
    // The rewritten message drops `contentParts` and `imageOrigin` and keeps
    // everything else the wire needs. `toolUseLoopMessages` builds this message
    // with only `role`/`content`/`contentParts`, so `tool_calls` and
    // `spillover_ref` are never set on it; `tool_call_id`/`name` are carried
    // anyway so the rewrite stays correct if another producer marks a message
    // `tool_result` in the future.
    return projected.map(message =>
      withheld.includes(message)
        ? {
            role: message.role,
            content: `${message.content}\n${notice}`,
            ...(message.tool_call_id ? { tool_call_id: message.tool_call_id } : {}),
            ...(message.name ? { name: message.name } : {}),
          }
        : message
    )
  }

  /**
   * Remove image parts with an invalid encoding from `tool_result` messages.
   * Returns `messages` itself when nothing was removed; otherwise a new array
   * in which only the affected messages are rebuilt (inputs are not mutated).
   *
   * Providers render `contentParts` instead of `content` when parts are
   * present, so when valid images remain the notice is appended both to
   * `content` and as a trailing text part. When no image remains, the message
   * drops `contentParts` and `imageOrigin` and is sent as plain text.
   */
  private removeMalformedToolImages(
    messages: ChatMessage[],
    method: ImageTransportOperation
  ): ChatMessage[] {
    let removedTotal = 0
    const sanitized = messages.map((message): ChatMessage => {
      if (message.imageOrigin !== 'tool_result' || !Array.isArray(message.contentParts)) {
        return message
      }
      const kept = message.contentParts.filter(
        part => !(part && part.type === 'image' && !isWellFormedImagePart(part))
      )
      const removed = message.contentParts.length - kept.length
      if (removed === 0) return message
      removedTotal += removed
      const notice = `[${removed} screenshot(s) returned by tool results were not forwarded: invalid image encoding]`
      const content = `${message.content}\n${notice}`
      if (kept.some(part => part && part.type === 'image')) {
        return { ...message, content, contentParts: [...kept, { type: 'text', text: notice }] }
      }
      const { contentParts: _dropped, imageOrigin: _origin, ...rest } = message
      return { ...rest, content }
    })
    if (removedTotal === 0) return messages
    logger.warn(
      {
        component: 'LlmPortAdapter',
        provider: this.providerName,
        model: this.model,
        method,
        count: removedTotal,
      },
      'tool screenshots removed before provider dispatch: invalid image encoding'
    )
    return sanitized
  }

  private recordUsage(
    requestId: string,
    requestUsageContext: UsageContext | undefined,
    usage:
      | {
          input_tokens: number
          output_tokens: number
          cache_read_tokens?: number
          cache_write_tokens?: number
        }
      | undefined
  ): void {
    const usageContext = requestUsageContext ?? this.defaultUsageContext
    if (usage && this.tokenCounter) {
      // Hermes `update_from_response`: stamp the counter with the
      // authoritative input_tokens so the next compaction decision can skip
      // the network call.
      this.tokenCounter.recordObservedUsage(usage)
    }
    // T2.2 — observe cache histograms whenever the response carried the
    // cache_*_tokens fields (Anthropic populates them; concat-fallback
    // providers leave them undefined, which we treat as 0 so the denominator
    // gauge still works for the canary).
    if (usage) {
      clerumPromptCacheInputTokens.observe(usage.input_tokens)
      clerumPromptCacheReadTokens.observe(usage.cache_read_tokens ?? 0)
      clerumPromptCacheWriteTokens.observe(usage.cache_write_tokens ?? 0)
    }
    // Durable per-session token counters. Deliberately BEFORE the UsageReporter
    // early-return below: persisting to `sessions.*_tokens` must not depend on
    // control-api being wired. `cache_*` are forwarded verbatim (undefined when
    // the provider doesn't report cache) so the session can track capability.
    //
    // `recordUsage` runs inside the LLM call's `try` block, so the sink is
    // wrapped: a throw here must NEVER bubble up and get mis-classified as a
    // provider error (which would abort an otherwise-successful turn). Token
    // accounting is best-effort telemetry — log and swallow.
    if (usage && this.onUsageRecorded) {
      try {
        this.onUsageRecorded({
          input_tokens: usage.input_tokens,
          output_tokens: usage.output_tokens,
          cache_read_tokens: usage.cache_read_tokens,
          cache_write_tokens: usage.cache_write_tokens,
        })
      } catch (err) {
        logger.error(
          { err: providerErrorDiagnostics(err) },
          'Usage sink failed; completion preserved'
        )
      }
    }
    if (!this.usageReporter || !this.staticContext || !usageContext || !usage) return
    if (this.providerName === 'codex-subscription') return
    const event: LlmUsageEvent = {
      request_id: requestId,
      ts: new Date().toISOString(),
      run_id: usageContext.traceContext?.runId ?? null,
      host_ref: this.staticContext.host_ref,
      context_ref: this.staticContext.context_ref,
      team_id: usageContext.team_id ?? null,
      provider: this.providerName,
      model: this.model,
      llm_secret_name: this.staticContext.llm_secret_name,
      source_kind: usageContext.source_kind,
      user_id: usageContext.user_id ?? null,
      sender: usageContext.sender ?? null,
      channel_type: usageContext.channel_type ?? null,
      recipe_name: usageContext.recipe_name ?? null,
      cron_job_id: usageContext.cron_job_id ?? null,
      task_id: usageContext.task_id ?? null,
      iteration: usageContext.iteration ?? null,
      input_tokens: usage.input_tokens,
      output_tokens: usage.output_tokens,
      cache_read_tokens: usage.cache_read_tokens,
      cache_write_tokens: usage.cache_write_tokens,
    }
    this.usageReporter.enqueue(event)
  }

  /**
   * Shared error path for provider calls. Classifies the error via the
   * provider, logs a structured line, and re-throws as an LlmError that
   * preserves the original SDK error as `cause`.
   *
   * Returns `never` so call sites can use it as a statement inside a catch
   * block without the compiler complaining about missing return paths.
   */
  private handleProviderError(err: unknown): never {
    if (err instanceof LlmError) throw err
    if (err instanceof VisualInputError) {
      throw new LlmError(
        err.message,
        this.providerName,
        err.code === 'limit_exceeded'
          ? LlmErrorCode.ContextLengthExceeded
          : LlmErrorCode.ApiCallFailed,
        false
      )
    }
    const classified = this.provider.classifyError(err)
    logger.info(
      {
        provider: this.providerName,
        model: this.model,
        code: classified.code,
        retryable: classified.retryable,
        diagnostics: providerErrorDiagnostics(err),
      },
      'LLM provider call failed'
    )
    throw new LlmError(
      classified.message,
      this.providerName,
      classified.code,
      classified.retryable,
      err as Error,
      classified.httpStatus,
      classified.providerCode
    )
  }

  modelName(): string {
    return this.model
  }
}