zidane/providers/anthropic

Mutate an Anthropic request in place to add cache breakpoints on the three stable prefixes:

1. System prompt — cache_control on the static prefix only (see below).
2. Tool definitions — last tool.
3. Conversation — last content block of the last message with content (an effort-only system message has none).

A fourth, lookback breakpoint goes on the message right before the latest assistant turn, whatever its role, when the request carries fewer than 4 markers (see the comment in the body).

Each breakpoint tells Anthropic to cache the prefix ending at that block; subsequent turns reuse the cached prefix and pay only for the delta. Safe no-op when any prefix is empty (no tools, empty system, etc.).

System-prompt boundary handling (SYSTEM_PROMPT_BOUNDARY):

• When originalSystem is provided AND carries the marker, the system block is rewritten as a 2-block array: static (cached) then dynamic (uncached). The caller is expected to have already stripped the marker from params.system via renderSystemForWire — this helper only re-splits to apply cache_control cleanly.
• When originalSystem is omitted or marker-free, the existing single- block treatment applies: cache_control on the whole system string.
• Array system prompts: existing semantics — cache_control lands on the last block. Callers building their own multi-block layout own the breakpoint placement.

function applyAnthropicCacheBreakpoints(
  params: MessageCreateParamsStreaming,
  originalSystem?: string,
  ttl?: CacheTtl,
): void

SDK constructor options for a resolved credential — the single place that decides which auth header goes on the wire.

Exported (and pure) so the header shape is test-pinned without a network round-trip: authToken → Authorization: Bearer …, apiKey → x-api-key, and apiKey: null alongside authToken is what suppresses x-api-key so a gateway sees exactly one credential.

function buildAnthropicClientOptions(
  apiKey: string,
  auth: { bearer: boolean; claudeCode: boolean },
  baseURL?: string,
  extraBetas?: readonly string[],
  extraHeaders?: Record<string, string>,
): Record<string, unknown>

Classify an Anthropic SDK / HTTP error for typed-error wrapping.

• prompt is too long (400 invalid_request_error) → context_exceeded.
• 'tool_use' ids were found without 'tool_result' blocks / 'tool_result must be preceded by a tool_call' (400) → tool_pairing_corruption. The local repair pass should have caught this — the typed error tells consumers their pre-send pipeline is shipping orphaned blocks somehow (custom context:transform hook, bypassed loop, mid-stream session edit) so they can patch the root cause instead of chasing 400s.
• A rate limit, spent credit or overload (429, 529, billing_error, also mid-stream) → provider_error worded by describeProviderLimit, with the server's reset (see classifyProviderLimit for when it stops retrying).
• Any other Anthropic APIError-shaped value → provider_error with the native status/type code.
• Unknown errors → null (loop wraps in AgentProviderError generically).

Anthropic's wire error shape is { type: 'error', error: { type, message } } — the SDK stores the parsed body on err.error. We walk both levels so callers see the most specific providerCode we can find.

function classifyAnthropicError(err: unknown, label?: string): ClassifiedError | null

Decide how to translate a ThinkingLevel into Anthropic's request shape. Pure / synchronous — exported so tests can assert routing without standing up the SDK.

Routing rules:

• 'off' → null (no thinking field, no effort hint).
• 'adaptive' → adaptive thinking with no effort hint (model decides everything). When taskBudget is set, it is carried as taskBudgetTokens and emitted as output_config.task_budget — the native whole-task thinking cap. LEGACY: when customBudget is set, it is carried as maxTokensCap so the request builder caps max_tokens accordingly — this clamps the whole response envelope (text and tool-call JSON included), which is the wrong knob for bounding thinking now that taskBudget exists; kept only for callers who already depend on it. Prefer taskBudget.
• Budgeted levels → adaptive thinking with an effort hint (plus taskBudgetTokens when taskBudget is set), unless customBudget is provided.
• Any level + customBudget → explicit-budget enabled path, carrying the level's effort hint alongside the budget. The caller has opted into precise budget control and accepts the Anthropic deprecation warning that comes with it on opus 4.6+. 'adaptive' is the sole exception: it never falls back to enabled, since adaptive is the current Anthropic API surface for self-budgeted thinking. taskBudget is adaptive-only and ignored on this path.
• effortHint: false (default true) strips the effort hint from every shape — budgeted levels plan plain adaptive and the customBudget path plans enabled with no output_config.effort — for Anthropic models that reject the effort field.

function planAnthropicThinking(
  level: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'adaptive',
  customBudget?: number,
  taskBudget?: number,
  effortHint?: boolean,
): AnthropicThinkingPlan | null

Resolve a model's max output tokens. Prefers pi-ai's bundled registry — the authoritative source the SDK itself uses to build requests, so e.g. Opus 4.x reports its full native 128K (no extended-output beta required) — and falls back to defaultAnthropicMaxTokens only when the registry lacks the model. Used as BOTH the default (when the caller leaves maxTokens unset) and a hard clamp, since a max_tokens above the model's max would 400.

The clamp is only as good as the ceiling's provenance, so an explicit caller maxTokens can RAISE the fallback: models the registry doesn't know are mostly ids that never appear in pi-ai's anthropic registry — Bedrock ids (global.anthropic.claude-*) and non-Anthropic models served over the Anthropic wire (openai.gpt-* on Bedrock, gateway aliases). For the latter the fallback degrades to the 32000 catch-all; for the former the family match yields a deliberately conservative non-beta floor. Clamping a caller who knows the real ceiling down to either silently truncates long generations mid-write (observed as turns pinned at exactly 32000 tokens).

It can only raise, never lower: the caller's maxTokens is a cap on the VISIBLE response, already enforced as max_tokens itself, whereas this value is the model's physical ceiling. Letting it lower the ceiling would break the enabled thinking path's invariant that the budget sits ON TOP of the response cap — the budget would be shrunk to share the caller's cap, or dropped entirely once no satisfiable budget fits.

A registry-backed max always wins over the caller — above it the provider 400s. A CATALOG entry (behavior.modelCatalog / setModelCatalog) outranks even that: it's an explicit claim about a model whose registry entry may be absent, stale, or an alias for something else entirely.

function resolveAnthropicMaxOutput(
  modelId: string,
  explicitMaxTokens?: number,
  catalog?: ModelCatalog,
): Promise<number>

Amazon Bedrock mode for the anthropic provider.

Routes the identical Messages wire shape through @anthropic-ai/bedrock-sdk (AnthropicBedrock), which signs requests with SigV4 instead of an Anthropic API key. Credentials resolve through the standard AWS chain — AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (+ AWS_SESSION_TOKEN) env vars, shared config, instance roles — so no ANTHROPIC_API_KEY is needed or consulted.

Model ids are Bedrock-shaped (e.g. global.anthropic.claude-haiku-4-5-20251001-v1:0); pass one as defaultModel or per run.

interface AnthropicBedrockConfig

Server-side context-management config — the body of context_management on the Messages API. Typed loosely (Record-of-unknown) so we don't pin a specific SDK schema version: the SDK's non-beta Messages types do not include this field, but the wire format is stable behind the context-management-2025-06-27 beta.

See: https://docs.anthropic.com/en/docs/build-with-claude/context-management

interface AnthropicContextManagement

Description of the Anthropic-side thinking configuration derived from a ThinkingLevel. null means no thinking-related field should be set on the request.

Two shapes:

• adaptive — thinking.type='adaptive'. The model self-budgets per turn. When effort is set, also emits output_config.effort to hint at the level of reasoning the caller wants. This is the post-Claude-4.6 default for level-based control and avoids the thinking.type='enabled' deprecation warning. When maxTokensCap is set, the request builder reduces max_tokens to min(max_tokens, maxTokensCap) — adaptive thinks and replies inside one envelope, so capping the envelope soft-bounds the thinking too.
• enabled — explicit-budget path: thinking.type='enabled' with an explicit budget_tokens. maxTokensBump is added to the request's max_tokens so the budget sits on top of the response cap. When the caller's level maps to an effort tier, effort is carried too and emitted as output_config.effort alongside the explicit budget — both fields are valid together on 4.6+ models. The only way to pin a precise token budget; Anthropic emits a deprecation warning for this shape on opus 4.6+, so we only route here when the caller explicitly sets behavior.thinkingBudget.

In both shapes Anthropic requires temperature to be 1.

type AnthropicThinkingPlan =
  | { budgetTokens: number; effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max'; kind: 'enabled'; maxTokensBump: number }
  | { effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max'; kind: 'adaptive'; maxTokensCap?: number; taskBudgetTokens?: number }