Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* 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
}
}
}