Skip to content

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

TypeScript
16.0 KB
Raw Blame
/**
 * Anthropic Claude LLM provider with tool/function calling support.
 */
import Anthropic from '@anthropic-ai/sdk'
import { LlmErrorCode } from '../core/errors'
import type { SystemPromptParts } from '../core/reasoning/systemPrompt'
import {
  AnthropicTokenCounter,
  type AnthropicTokenCounterOptions,
} from '../core/tokenizer/anthropicTokenCounter'
import type { TokenCounter } from '../core/tokenizer/tokenCounter'
import {
  CompletionResponse,
  ChatMessage as CoreChatMessage,
  FinishReason,
  ToolCompletionResponse,
  ToolDefinition,
} from '../core/types'
import { logger } from '../logger'
import { resolveOfficialVisualDeliveryLimits } from '../visualInput/deliveryLimits'
import { assertVisualRequestFits } from '../visualInput/requestPolicy'
import { convertToClaudeMessages, separateSystemMessage } from './claude/messageTranslate'
import { classifyByHttpStatus, classifyUnknown } from './errorClassification'
import type { ImageTransportOperation } from './imageInput'
import type { LlmProvider } from './registryCore'
import type { ClassifiedError, SingleTurnProvider } from './types'

export class ClaudeProvider implements SingleTurnProvider {
  private client: Anthropic
  private defaultModel: string

  getVisualDeliveryLimits(operation: ImageTransportOperation) {
    return resolveOfficialVisualDeliveryLimits('claude', this.client.baseURL, operation)
  }

  constructor(apiKeyOrClient: string | Anthropic, defaultModel: string = 'claude-sonnet-4-6') {
    if (typeof apiKeyOrClient === 'string') {
      this.client = new Anthropic({ apiKey: apiKeyOrClient })
    } else {
      this.client = apiKeyOrClient
    }
    this.defaultModel = defaultModel
    logger.info({ model: defaultModel }, 'Claude transport initialized')
  }

  /**
   * Get the provider type.
   */
  getProviderType(): LlmProvider {
    return 'claude'
  }

  /**
   * Build the provider-aware token counter. Keeps the SDK client private —
   * the counter receives it at construction time and the rest of the codebase
   * never sees the raw `Anthropic` instance. Key rotation that swaps this
   * provider also brings a fresh counter for free.
   */
  createTokenCounter(modelName: string, options?: AnthropicTokenCounterOptions): TokenCounter {
    return new AnthropicTokenCounter(this.client, modelName, options)
  }

  classifyError(err: unknown): ClassifiedError {
    // Anthropic surfaces a modeled `error.type` that is more precise than the
    // HTTP status (a live model can still 404 with `not_found_error`). Classify
    // by type FIRST; the set is open by contract, so unmatched types fall
    // through to the status-based classifier below. (spec 02 §3.1)
    //
    // Nesting note: on `Anthropic.APIError`, `.error` is the FULL response
    // envelope `{ type:'error', error:{ type, message } }`, so the modeled type
    // lives at `.error.error.type` (`.error.type` is the constant 'error'). Read
    // the inner level first, with the outer level as a defensive fallback for
    // any non-enveloped shape.
    const anthropicErr = err as {
      status?: unknown
      message?: string
      error?: { type?: string; message?: string; error?: { type?: string; message?: string } }
    }
    const bodyType = anthropicErr?.error?.error?.type ?? anthropicErr?.error?.type
    const httpStatus = typeof anthropicErr?.status === 'number' ? anthropicErr.status : undefined
    const rawMsg =
      anthropicErr?.error?.error?.message ??
      anthropicErr?.error?.message ??
      anthropicErr?.message ??
      'Unknown Claude error'
    if (bodyType) {
      const byType = ((): ClassifiedError | null => {
        switch (bodyType) {
          case 'not_found_error':
            // Retired or inaccessible model — ambiguous by design; non-retryable
            // and NOT a failover trigger.
            return { code: LlmErrorCode.ModelNotAvailable, retryable: false, message: rawMsg }
          case 'overloaded_error':
            return { code: LlmErrorCode.ModelOverloaded, retryable: true, message: rawMsg }
          case 'billing_error':
            // Genuine billing / credit exhaustion — Anthropic's dedicated quota
            // channel (like body `insufficient_quota`). Stays on InsufficientQuota.
            return { code: LlmErrorCode.InsufficientQuota, retryable: false, message: rawMsg }
          case 'permission_error':
            // A 403: account access / IAM permission — an identity/authorization
            // failure, not billing. Classify as AuthenticationFailed so it lands
            // on the `auth` failover class uniformly with the other arms (R1-M1).
            return { code: LlmErrorCode.AuthenticationFailed, retryable: false, message: rawMsg }
          default:
            return null
        }
      })()
      if (byType) return { ...byType, httpStatus, providerCode: bodyType }
    }

    const httpClassification = classifyByHttpStatus(err)
    if (httpClassification) {
      // The shared classifier recovers providerCode from the OUTER envelope,
      // where Anthropic's modeled type is the constant 'error'. When the SDK gave
      // us the inner modeled type, prefer it so an unmapped Anthropic error (e.g.
      // invalid_request_error / authentication_error) surfaces its real code
      // instead of 'error' (R1-L1). No-op on non-enveloped shapes, where bodyType
      // already equals the shared classifier's providerCode.
      const classified =
        bodyType && httpClassification.providerCode !== bodyType
          ? { ...httpClassification, providerCode: bodyType }
          : httpClassification
      // Anthropic quirk: insufficient credit is reported as HTTP 400
      // (not 402), detectable only by message substring.
      if (
        classified.code === LlmErrorCode.ApiCallFailed &&
        /credit balance is too low/i.test(classified.message)
      ) {
        return {
          ...classified,
          code: LlmErrorCode.InsufficientQuota,
          retryable: false,
          // Prefer the inner-level message: on a real Anthropic envelope the
          // shared classifier only sees the outer `${status} {json}` string.
          message: rawMsg,
        }
      }
      return classified
    }
    return classifyUnknown(err)
  }

  // ─── Single-Turn Methods ──────────────────────────────────

  async completeSingleTurn(
    messages: CoreChatMessage[],
    options?: { max_tokens?: number; temperature?: number; signal?: AbortSignal }
  ): Promise<CompletionResponse> {
    assertVisualRequestFits(messages, messages, false, this.getVisualDeliveryLimits('complete'))
    const { systemPrompt, claudeMessages } = this.separateSystemMessage(messages)

    const response = await this.client.messages.create(
      {
        model: this.defaultModel,
        system: systemPrompt || undefined,
        messages: claudeMessages.map(m => {
          return {
            role: m.role as 'user' | 'assistant',
            content: m.content,
          }
        }),
        max_tokens: options?.max_tokens ?? 4096,
        temperature: options?.temperature,
      },
      { signal: options?.signal }
    )

    const textContent = response.content
      .filter((b): b is Anthropic.TextBlock => b.type === 'text')
      .map(b => b.text)
      .join('')

    const usage = response.usage
    const usageReported =
      usage != null &&
      Number.isInteger(usage.input_tokens) &&
      usage.input_tokens >= 0 &&
      Number.isInteger(usage.output_tokens) &&
      usage.output_tokens >= 0
    return {
      content: textContent,
      usage: {
        input_tokens: usage?.input_tokens ?? 0,
        output_tokens: usage?.output_tokens ?? 0,
        total_tokens: (usage?.input_tokens ?? 0) + (usage?.output_tokens ?? 0),
      },
      usage_reported: usageReported,
      finish_reason: this.mapStopReason(response.stop_reason),
    }
  }

  async completeSingleTurnWithTools(
    messages: CoreChatMessage[],
    tools: ToolDefinition[],
    options?: {
      max_tokens?: number
      temperature?: number
      tool_choice?: string
      signal?: AbortSignal
      verifyImageInput?: boolean
    }
  ): Promise<ToolCompletionResponse> {
    const { systemPrompt, claudeMessages } = this.separateSystemMessage(messages)
    const formattedMessages = this.convertToClaudeMessages(claudeMessages)

    const claudeTools = tools.map(t => ({
      name: t.name,
      description: t.description,
      input_schema: t.parameters as Anthropic.Tool['input_schema'],
    }))

    const request: Anthropic.MessageCreateParamsNonStreaming = {
      model: this.defaultModel,
      system: systemPrompt || undefined,
      messages: formattedMessages,
      tools: claudeTools.length > 0 ? claudeTools : undefined,
      max_tokens: options?.max_tokens ?? 4096,
      temperature: options?.temperature,
    }
    assertVisualRequestFits(
      messages,
      request,
      options?.verifyImageInput === true,
      this.getVisualDeliveryLimits('completeWithTools')
    )
    const response = await this.client.messages.create(request, { signal: options?.signal })

    const textContent =
      response.content
        .filter((b): b is Anthropic.TextBlock => b.type === 'text')
        .map(b => b.text)
        .join('') || null

    const toolUseBlocks = response.content.filter(
      (b): b is Anthropic.ToolUseBlock => b.type === 'tool_use'
    )
    const toolCalls =
      toolUseBlocks.length > 0
        ? toolUseBlocks.map(b => ({
            id: b.id,
            name: b.name,
            arguments: b.input as Record<string, unknown>,
          }))
        : null

    return {
      content: textContent,
      tool_calls: toolCalls,
      usage: {
        input_tokens: response.usage.input_tokens,
        output_tokens: response.usage.output_tokens,
        total_tokens: response.usage.input_tokens + response.usage.output_tokens,
      },
      finish_reason: this.mapStopReason(response.stop_reason),
    }
  }

  // ─── T2.2 Cache-aware single-turn methods ─────────────────────────

  /**
   * T2.2 — Cache-aware completion. Emits the `system` field as an array of
   * `TextBlockParam` with `cache_control: { type: 'ephemeral' }` on every
   * tier so Anthropic prefix-caches the entire system block. Tools travel in
   * their dedicated parameter (no `tools` text in the system) sorted by name
   * so add/remove of a single tool only shifts the delta in the `tools` cache
   * slot, leaving the surrounding entries stable.
   */
  async completeSingleTurnWithToolsAndCache(
    parts: SystemPromptParts,
    messages: CoreChatMessage[],
    tools: ToolDefinition[],
    options?: {
      max_tokens?: number
      temperature?: number
      tool_choice?: string
      signal?: AbortSignal
      verifyImageInput?: boolean
    }
  ): Promise<ToolCompletionResponse> {
    const formattedMessages = this.convertToClaudeMessages(messages)
    const claudeTools = tools
      .slice()
      .sort((a, b) => a.name.localeCompare(b.name))
      .map(t => ({
        name: t.name,
        description: t.description,
        input_schema: t.parameters as Anthropic.Tool['input_schema'],
      }))

    const systemBlocks: Array<Anthropic.TextBlockParam> = []
    if (parts.stable) {
      systemBlocks.push({
        type: 'text',
        text: parts.stable,
        cache_control: { type: 'ephemeral' },
      } as Anthropic.TextBlockParam)
    }
    if (parts.context) {
      systemBlocks.push({
        type: 'text',
        text: parts.context,
        cache_control: { type: 'ephemeral' },
      } as Anthropic.TextBlockParam)
    }

    const request: Anthropic.MessageCreateParamsNonStreaming = {
      model: this.defaultModel,
      system: systemBlocks.length > 0 ? systemBlocks : undefined,
      messages: formattedMessages,
      tools: claudeTools.length > 0 ? claudeTools : undefined,
      max_tokens: options?.max_tokens ?? 4096,
      temperature: options?.temperature,
    }
    assertVisualRequestFits(
      messages,
      request,
      options?.verifyImageInput === true,
      this.getVisualDeliveryLimits('completeWithToolsAndCache')
    )
    const response = await this.client.messages.create(request, { signal: options?.signal })

    const textContent =
      response.content
        .filter((b): b is Anthropic.TextBlock => b.type === 'text')
        .map(b => b.text)
        .join('') || null

    const toolUseBlocks = response.content.filter(
      (b): b is Anthropic.ToolUseBlock => b.type === 'tool_use'
    )
    const toolCalls =
      toolUseBlocks.length > 0
        ? toolUseBlocks.map(b => ({
            id: b.id,
            name: b.name,
            arguments: b.input as Record<string, unknown>,
          }))
        : null

    // P1-006: map Anthropic SDK field names to mcp-host's abbreviated schema.
    const u = response.usage as Anthropic.Usage & {
      cache_read_input_tokens?: number | null
      cache_creation_input_tokens?: number | null
    }
    return {
      content: textContent,
      tool_calls: toolCalls,
      usage: {
        input_tokens: u.input_tokens,
        output_tokens: u.output_tokens,
        total_tokens: u.input_tokens + u.output_tokens,
        cache_read_tokens: u.cache_read_input_tokens ?? 0,
        cache_write_tokens: u.cache_creation_input_tokens ?? 0,
      },
      finish_reason: this.mapStopReason(response.stop_reason),
    }
  }

  /**
   * T2.2 — Cache-aware completion without tools. Same wire-shape decisions as
   * `completeSingleTurnWithToolsAndCache` minus the `tools` parameter. Used
   * by `PressureContextManager.summarize` when wired through the cache path
   * (rare; the tool-less path is mostly background summarization).
   */
  async completeSingleTurnAndCache(
    parts: SystemPromptParts,
    messages: CoreChatMessage[],
    options?: { max_tokens?: number; temperature?: number; signal?: AbortSignal }
  ): Promise<CompletionResponse> {
    const claudeMessages = this.convertToClaudeMessages(messages)
    const systemBlocks: Array<Anthropic.TextBlockParam> = []
    if (parts.stable) {
      systemBlocks.push({
        type: 'text',
        text: parts.stable,
        cache_control: { type: 'ephemeral' },
      } as Anthropic.TextBlockParam)
    }
    if (parts.context) {
      systemBlocks.push({
        type: 'text',
        text: parts.context,
        cache_control: { type: 'ephemeral' },
      } as Anthropic.TextBlockParam)
    }

    const request: Anthropic.MessageCreateParamsNonStreaming = {
      model: this.defaultModel,
      system: systemBlocks.length > 0 ? systemBlocks : undefined,
      messages: claudeMessages,
      max_tokens: options?.max_tokens ?? 4096,
      temperature: options?.temperature,
    }
    assertVisualRequestFits(
      messages,
      request,
      false,
      this.getVisualDeliveryLimits('completeAndCache')
    )
    const response = await this.client.messages.create(request, { signal: options?.signal })

    const textContent = response.content
      .filter((b): b is Anthropic.TextBlock => b.type === 'text')
      .map(b => b.text)
      .join('')

    const u = response.usage as Anthropic.Usage & {
      cache_read_input_tokens?: number | null
      cache_creation_input_tokens?: number | null
    }
    return {
      content: textContent,
      usage: {
        input_tokens: u.input_tokens,
        output_tokens: u.output_tokens,
        total_tokens: u.input_tokens + u.output_tokens,
        cache_read_tokens: u.cache_read_input_tokens ?? 0,
        cache_write_tokens: u.cache_creation_input_tokens ?? 0,
      },
      finish_reason: this.mapStopReason(response.stop_reason),
    }
  }

  private separateSystemMessage(messages: CoreChatMessage[]): {
    systemPrompt: string | null
    claudeMessages: CoreChatMessage[]
  } {
    return separateSystemMessage(messages)
  }

  private convertToClaudeMessages(messages: CoreChatMessage[]): Anthropic.MessageParam[] {
    return convertToClaudeMessages(messages)
  }

  private mapStopReason(reason: string | null | undefined): FinishReason {
    switch (reason) {
      case 'end_turn':
        return FinishReason.Stop
      case 'max_tokens':
        return FinishReason.Length
      case 'tool_use':
        return FinishReason.ToolUse
      default:
        return FinishReason.Unknown
    }
  }
}