Rulvar API reference / @rulvar/anthropic
@rulvar/anthropic
First-class Anthropic provider adapter over the official @anthropic-ai/sdk: thinking-block replay with signatures, cache hint compilation, pause_turn continuation, typed refusal outcomes, and usage normalization. Exports the anthropic adapter factory; models are addressed as 'anthropic:<model>' in routing.
Part of Rulvar, an embeddable TypeScript engine for durable, budget-bounded multi-agent LLM workflows, where a completed LLM call is never paid for twice. Full documentation: docs.rulvar.com.
Install
bash
pnpm add @rulvar/core @rulvar/anthropicThe umbrella package @rulvar/rulvar already bundles this adapter.
Documentation
License
Classes
| Class | Description |
|---|---|
| IdMap | Bijective canonical-to-wire tool-call id map. |
Interfaces
| Interface | Description |
|---|---|
| AnthropicAdapterOptions | - |
| AnthropicClientLike | The client sub-surface the adapter consumes; injectable for tests. |
| AnthropicModelInfo | - |
| MappedStop | - |
| TurnMapping | - |
Type Aliases
| Type Alias | Description |
|---|---|
| AnthropicSdkOptions | Official SDK construction options forwarded verbatim to new Anthropic(...), minus maxRetries: Rulvar owns retries and wall-clock, so SDK autoretries stay disabled no matter what is passed here. This is the production surface for every credential mode the SDK supports beyond a plain API key: bearer authToken, an AccessTokenProvider via credentials, an AnthropicConfig via config (OIDC/workload-identity federation included), a named profile, plus fetch, timeout, and defaultHeaders. |
| AnthropicStreamEvent | Raw Messages API stream events, structurally typed. |
| Block | A raw Messages API content block, structurally typed. |
Variables
| Variable | Description |
|---|---|
| ANTHROPIC_MODELS | Static seed table naming the current model set. |
| ANTHROPIC_PRICING | The seed pricing rows as a versioned price table, keyed by full ModelRef under the adapter's fixed id 'anthropic'. Pass it to createEngine({ pricing }) so the run journals a concrete pricingVersion instead of 'unpriced': the versioned table wins over the caps fallback by rule, and a later table revision surfaces as explicit configuration drift on resume rather than a silent reinterpretation. Extend or override rows by spreading models into your own table with a new version string (the documented path for the Sonnet 5 promotion ending on 2026-08-31). |
| DEFAULT_PAUSE_TURN_MAX_CONTINUATIONS | pause_turn continuation cap. |
Functions
| Function | Description |
|---|---|
| anthropic | @rulvar/anthropic: the first-class Anthropic adapter on the July 2026 Messages API surface. |
| anthropicErrorToWire | Projects an SDK/API error into the retryable WireError vocabulary: 429 rate limits surface retryAfterMs and the x-ratelimit-* buckets; 529 overloaded and 5xx are retryable transport; everything else is terminal transport. Adapters never sleep internally. |
| anthropicModelInfo | - |
| buildAnthropicParams | Builds Messages API params from a ChatRequest. cacheHint compiles into cache_control breakpoints; beyond the provider cap of 4 the DEEPEST breakpoints are kept and the shallowest dropped, deterministically. |
| mapAnthropicStream | Maps one Messages API stream into ChatEvents, yielding each canonical event AS the corresponding provider event is consumed: the consumer's pull drives the provider read (natural backpressure, no buffering, no detached work). The generator's RETURN value carries the accumulated turn state the adapter needs for pause_turn continuation. Yields an early usage event from message_start (the input side is known immediately) and exactly one terminal finish when the stream reaches message_stop. A stream that pauses (pause_turn) or ends before message_stop yields NO terminal event of its own: the return value's pauseTurn and finished flags report which case happened, and the anthropic() adapter turns a truncated read (finished false without a pause) into the retryable transport error the contract requires, so a direct mapper consumer must check the flags rather than wait for an error event. carryRetained holds thinking blocks from earlier pause_turn continuations of the same turn so the terminal finish ships the whole turn's retention payload (M4-T02). |
| mapStopReason | The stop-reason table. pause_turn never surfaces as a canonical finish: the adapter continues internally. |
| normalizeAnthropicUsage | Normalizes Messages API usage under the Usage invariant: Anthropic reports input_tokens EXCLUDING cache reads and writes, so the canonical inputTokens is the sum of all three. The cache_creation breakdown (ephemeral_5m_input_tokens / ephemeral_1h_input_tokens) fills the canonical TTL split (RV810) when it agrees with the flat total, so the 1h premium prices at its own rate downstream; a breakdown that contradicts the flat total is dropped rather than shipped as a broken invariant (the flat total is the billable number, and the undifferentiated 5m-rate fold is the historical conservative default). With no flat field, the breakdown IS the total. |