@effect-uai/anthropic 0.10.0 → 0.12.0

package/dist/usage.test.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/usage.test.mjs

@@ -0,0 +1,46 @@
+import { emptyAccumulator, mergeUsage } from "./codec.mjs";
+import { applyEvent } from "./streamEvents.mjs";
+import { n as describe, r as it, t as globalExpect } from "./test.DNmyFkvJ-CPKukVWS.mjs";
+//#region src/usage.test.ts
+const wire = {
+	input_tokens: 94,
+	output_tokens: 210,
+	cache_read_input_tokens: 31851,
+	cache_creation_input_tokens: 604
+};
+describe("mergeUsage", () => {
+	it("keeps all three input buckets, not just cache reads", () => {
+		const usage = mergeUsage(emptyAccumulator, wire).usage;
+		globalExpect(usage.input_tokens).toBe(94);
+		globalExpect(usage.input_tokens_details?.cached_tokens).toBe(31851);
+		globalExpect(usage.input_tokens_details?.cache_write_tokens).toBe(604);
+	});
+	it("totals every input bucket plus output", () => {
+		const usage = mergeUsage(emptyAccumulator, wire).usage;
+		globalExpect(usage.total_tokens).toBe(32759);
+	});
+});
+describe("streamed usage", () => {
+	it("computes a non-stale total across message_start and message_delta", () => {
+		const usage = applyEvent(applyEvent(emptyAccumulator, {
+			type: "message_start",
+			message: { usage: {
+				input_tokens: 94,
+				output_tokens: 1,
+				cache_read_input_tokens: 31851,
+				cache_creation_input_tokens: 604
+			} }
+		}), {
+			type: "message_delta",
+			delta: { stop_reason: "end_turn" },
+			usage: { output_tokens: 210 }
+		}).usage;
+		globalExpect(usage.output_tokens).toBe(210);
+		globalExpect(usage.input_tokens_details?.cache_write_tokens).toBe(604);
+		globalExpect(usage.total_tokens).toBe(32759);
+	});
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=usage.test.mjs.map

package/dist/usage.test.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.test.mjs","names":[],"sources":["../src/usage.test.ts"],"sourcesContent":["import { describe, expect, it } from \"vitest\"\nimport { type WireUsage, emptyAccumulator, mergeUsage } from \"./codec.js\"\nimport { type ProviderEvent, applyEvent } from \"./streamEvents.js\"\n\n// A completed cached turn: input split across post-breakpoint tokens, cache\n// reads, and cache writes, all billed separately.\nconst wire: WireUsage = {\n  input_tokens: 94,\n  output_tokens: 210,\n  cache_read_input_tokens: 31851,\n  cache_creation_input_tokens: 604,\n}\n\ndescribe(\"mergeUsage\", () => {\n  it(\"keeps all three input buckets, not just cache reads\", () => {\n    const usage = mergeUsage(emptyAccumulator, wire).usage\n    expect(usage.input_tokens).toBe(94)\n    expect(usage.input_tokens_details?.cached_tokens).toBe(31851)\n    expect(usage.input_tokens_details?.cache_write_tokens).toBe(604)\n  })\n\n  it(\"totals every input bucket plus output\", () => {\n    const usage = mergeUsage(emptyAccumulator, wire).usage\n    expect(usage.total_tokens).toBe(94 + 31851 + 604 + 210)\n  })\n})\n\ndescribe(\"streamed usage\", () => {\n  // Anthropic sends input + cache on message_start and the final output_tokens\n  // on message_delta. total_tokens must reflect the accumulated buckets, not\n  // the (input + initial output) figure frozen at message_start.\n  it(\"computes a non-stale total across message_start and message_delta\", () => {\n    const start: ProviderEvent = {\n      type: \"message_start\",\n      message: {\n        usage: {\n          input_tokens: 94,\n          output_tokens: 1,\n          cache_read_input_tokens: 31851,\n          cache_creation_input_tokens: 604,\n        },\n      },\n    }\n    const delta: ProviderEvent = {\n      type: \"message_delta\",\n      delta: { stop_reason: \"end_turn\" },\n      usage: { output_tokens: 210 },\n    }\n    const usage = applyEvent(applyEvent(emptyAccumulator, start), delta).usage\n    expect(usage.output_tokens).toBe(210)\n    expect(usage.input_tokens_details?.cache_write_tokens).toBe(604)\n    expect(usage.total_tokens).toBe(94 + 31851 + 604 + 210)\n  })\n})\n"],"mappings":";;;;AAMA,MAAM,OAAkB;CACtB,cAAc;CACd,eAAe;CACf,yBAAyB;CACzB,6BAA6B;CAC9B;AAED,SAAS,oBAAoB;AAC3B,IAAG,6DAA6D;EAC9D,MAAM,QAAQ,WAAW,kBAAkB,KAAK,CAAC;AACjD,eAAO,MAAM,aAAa,CAAC,KAAK,GAAG;AACnC,eAAO,MAAM,sBAAsB,cAAc,CAAC,KAAK,MAAM;AAC7D,eAAO,MAAM,sBAAsB,mBAAmB,CAAC,KAAK,IAAI;GAChE;AAEF,IAAG,+CAA+C;EAChD,MAAM,QAAQ,WAAW,kBAAkB,KAAK,CAAC;AACjD,eAAO,MAAM,aAAa,CAAC,KAAK,MAAuB;GACvD;EACF;AAEF,SAAS,wBAAwB;AAI/B,IAAG,2EAA2E;EAiB5E,MAAM,QAAQ,WAAW,WAAW,kBAAkB;GAfpD,MAAM;GACN,SAAS,EACP,OAAO;IACL,cAAc;IACd,eAAe;IACf,yBAAyB;IACzB,6BAA6B;IAC9B,EACF;GAOwD,CAAC,EAAE;GAJ5D,MAAM;GACN,OAAO,EAAE,aAAa,YAAY;GAClC,OAAO,EAAE,eAAe,KAAK;GAEoC,CAAC,CAAC;AACrE,eAAO,MAAM,cAAc,CAAC,KAAK,IAAI;AACrC,eAAO,MAAM,sBAAsB,mBAAmB,CAAC,KAAK,IAAI;AAChE,eAAO,MAAM,aAAa,CAAC,KAAK,MAAuB;GACvD;EACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-uai/anthropic",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Anthropic Messages API provider for @effect-uai/core.",
   "keywords": [
     "ai",
@@ -43,13 +43,13 @@
     "access": "public"
   },
   "devDependencies": {
-    "effect": "4.0.0-beta.57",
+    "effect": "4.0.0-beta.94",
     "typescript": "^6.0.3",
-    "@effect-uai/core": "0.10.0"
+    "@effect-uai/core": "0.12.0"
   },
   "peerDependencies": {
     "@effect-uai/core": ">=0.2.0 <1",
-    "effect": "4.0.0-beta.57"
+    "effect": ">=4.0.0-beta.94 <5.0.0"
   },
   "scripts": {
     "build": "tsdown",

package/src/Anthropic.ts

@@ -19,10 +19,13 @@ import {
   turnFromStream,
 } from "@effect-uai/core/LanguageModel"
 import * as SSE from "@effect-uai/core/SSE"
-import { descriptorsOf } from "@effect-uai/core/Tool"
+import { descriptorsOf, providerToolsOf } from "@effect-uai/core/Tool"
 import { type Turn, TurnEvent } from "@effect-uai/core/Turn"
+import { renderProviderTools } from "./AnthropicTools.js"
 import {
   type Accumulator,
+  type CacheControl,
+  type CacheTtl,
   type ThinkingConfig,
   accumulatorToTurn,
   buildRequestBody,
@@ -31,6 +34,13 @@ import {
 import type { AnthropicModel } from "./models.js"
 import { KnownProviderEvent, ProviderEvent, applyEvent } from "./streamEvents.js"
 
+export {
+  codeExecutionTool,
+  webSearchTool,
+  type WebSearchOptions,
+  type UserLocation,
+} from "./AnthropicTools.js"
+
 // ---------------------------------------------------------------------------
 // Public types
 // ---------------------------------------------------------------------------
@@ -111,6 +121,21 @@ export type Config = {
    * 4096 if neither is set.
    */
   readonly defaultMaxTokens?: number
+  /**
+   * Prompt caching. Off by default, so the library stays unopinionated about
+   * a setting that changes billing. `true` is `{}`: cache with the 5-minute
+   * default TTL.
+   *
+   * Anthropic caches the `tools` → `system` → `messages` prefix and moves the
+   * breakpoint forward as the conversation grows, so a long system prompt and
+   * tool definitions are paid for once rather than on every turn. Read
+   * `usage.input_tokens_details.cached_tokens` to see it working.
+   *
+   * Mutating earlier history (rewriting an old message, compaction) breaks
+   * the prefix from that point on. Anthropic falls back to the longest
+   * unchanged prefix, so this costs savings but never correctness.
+   */
+  readonly promptCaching?: boolean | { readonly ttl?: CacheTtl }
 }
 
 const ANTHROPIC_VERSION = "2023-06-01"
@@ -131,19 +156,44 @@ const outputConfig = (request: AnthropicRequest): Option.Option<Record<string, u
 const resolvedMaxTokens = (cfg: Config, request: AnthropicRequest): number =>
   request.maxOutputTokens ?? cfg.defaultMaxTokens ?? FALLBACK_MAX_TOKENS
 
-const toolDescriptors = (
+/**
+ * One request-level breakpoint when caching is on. Anthropic places it on the
+ * last cacheable block itself, so nothing has to be marked per-block and the
+ * breakpoint stays correct as history grows.
+ */
+const cacheControlOf = (cfg: Config): Option.Option<CacheControl> =>
+  pipe(
+    Option.fromUndefinedOr(cfg.promptCaching),
+    Option.flatMap((opt) =>
+      opt === false
+        ? Option.none<CacheControl>()
+        : Option.some<CacheControl>({
+            type: "ephemeral",
+            ...(opt !== true && opt.ttl !== undefined && { ttl: opt.ttl }),
+          }),
+    ),
+  )
+
+const functionToolDescriptors = (
   request: AnthropicRequest,
+): ReadonlyArray<Record<string, unknown>> =>
+  descriptorsOf(request.tools).map((t) => ({
+    name: t.name,
+    description: t.description,
+    input_schema: t.inputSchema,
+  }))
+
+/**
+ * Merge the custom function-tool declarations with the native hosted-tool
+ * entries into the single `tools` array Anthropic expects. `providerWire` is
+ * pre-rendered (and validated) by the caller.
+ */
+const toolsWire = (
+  request: AnthropicRequest,
+  providerWire: ReadonlyArray<Record<string, unknown>>,
 ): Option.Option<ReadonlyArray<Record<string, unknown>>> => {
-  const descriptors = descriptorsOf(request.tools)
-  return descriptors.length > 0
-    ? Option.some(
-        descriptors.map((t) => ({
-          name: t.name,
-          description: t.description,
-          input_schema: t.inputSchema,
-        })),
-      )
-    : Option.none()
+  const tools = [...functionToolDescriptors(request), ...providerWire]
+  return tools.length > 0 ? Option.some(tools) : Option.none()
 }
 
 const toolChoiceWire = (request: AnthropicRequest): Option.Option<Record<string, unknown>> =>
@@ -260,6 +310,20 @@ const buildNativeStream = (cfg: Config) => {
     Stream.unwrap(
       Effect.gen(function* () {
         const structured = outputConfig(request)
+        const providerWire = yield* Result.match(
+          renderProviderTools(providerToolsOf(request.tools)),
+          {
+            onFailure: (e) =>
+              Effect.fail(
+                new AiError.Unsupported({
+                  provider: "anthropic",
+                  capability: e.capability,
+                  reason: e.reason,
+                }),
+              ),
+            onSuccess: (wire) => Effect.succeed(wire),
+          },
+        )
         const bodyResult = buildRequestBody({
           model: request.model,
           history: request.history,
@@ -269,10 +333,11 @@ const buildNativeStream = (cfg: Config) => {
           topK: Option.fromUndefinedOr(request.topK),
           stopSequences: Option.fromUndefinedOr(request.stopSequences),
           thinking: Option.fromUndefinedOr(request.thinking),
-          tools: toolDescriptors(request),
+          tools: toolsWire(request, providerWire),
           toolChoice: toolChoiceWire(request),
           userId: Option.fromUndefinedOr(request.user),
           outputConfig: structured,
+          cacheControl: cacheControlOf(cfg),
         })
 
         const body = yield* Result.match(bodyResult, {
@@ -354,7 +419,7 @@ export const toCanonical = <E, R>(
  * Build an `AnthropicService` value. For Layer-based setup, prefer `layer`.
  */
 export const make = (cfg: Config): Effect.Effect<AnthropicService, never, HttpClient.HttpClient> =>
-  Effect.map(HttpClient.HttpClient.asEffect(), (client) => {
+  Effect.map(HttpClient.HttpClient, (client) => {
     const streamNative: AnthropicService["streamNative"] = (request) =>
       buildNativeStream(cfg)(request).pipe(Stream.provideService(HttpClient.HttpClient, client))
     const streamTurn: AnthropicService["streamTurn"] = (request) =>

package/src/AnthropicTools.ts

@@ -0,0 +1,128 @@
+import { Match, Result, Schema } from "effect"
+import * as Tool from "@effect-uai/core/Tool"
+
+// ---------------------------------------------------------------------------
+// Anthropic provider-hosted tools. Each is a `Tool.provider` whose `config`
+// carries the version-dated wire `type` string plus its options; the renderer
+// maps it to a native entry appended to the `tools` array alongside custom
+// tools. The `inputSchema` is never sent (provider tools are partitioned out
+// of the custom-tool declarations), so `Tool.noInput` suffices.
+// Reference: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/web-search-tool
+// ---------------------------------------------------------------------------
+
+const WEB_SEARCH_TYPE = "web_search_20250305"
+const CODE_EXECUTION_TYPE = "code_execution_20250522"
+
+const UserLocation = Schema.Struct({
+  city: Schema.optional(Schema.String),
+  region: Schema.optional(Schema.String),
+  country: Schema.optional(Schema.String),
+  timezone: Schema.optional(Schema.String),
+})
+export type UserLocation = typeof UserLocation.Type
+
+const WebSearchConfig = Schema.Struct({
+  kind: Schema.Literal("web_search"),
+  type: Schema.String,
+  maxUses: Schema.optional(Schema.Number),
+  allowedDomains: Schema.optional(Schema.Array(Schema.String)),
+  blockedDomains: Schema.optional(Schema.Array(Schema.String)),
+  userLocation: Schema.optional(UserLocation),
+})
+
+const CodeExecutionConfig = Schema.Struct({
+  kind: Schema.Literal("code_execution"),
+  type: Schema.String,
+})
+
+/** Discriminated config for an Anthropic hosted tool. */
+export const AnthropicToolConfig = Schema.Union([WebSearchConfig, CodeExecutionConfig])
+export type AnthropicToolConfig = typeof AnthropicToolConfig.Type
+
+export type WebSearchOptions = {
+  readonly maxUses?: number
+  readonly allowedDomains?: ReadonlyArray<string>
+  readonly blockedDomains?: ReadonlyArray<string>
+  readonly userLocation?: UserLocation
+}
+
+/** Anthropic-hosted web search. */
+export const webSearchTool = (opts: WebSearchOptions = {}) =>
+  Tool.provider({
+    name: "web_search",
+    description: "Search the web, executed by Anthropic.",
+    inputSchema: Tool.noInput,
+    provider: "anthropic",
+    config: { kind: "web_search", type: WEB_SEARCH_TYPE, ...opts } as const,
+  })
+
+/** Anthropic-hosted code execution (Python sandbox). */
+export const codeExecutionTool = Tool.provider({
+  name: "code_execution",
+  description: "Run Python in a sandbox, executed by Anthropic.",
+  inputSchema: Tool.noInput,
+  provider: "anthropic",
+  config: { kind: "code_execution", type: CODE_EXECUTION_TYPE } as const,
+})
+
+/**
+ * A provider tool this adapter cannot render — a foreign `provider` or an
+ * unrecognized `config`. Carried as data so `Anthropic.ts` can lift it into a
+ * typed `AiError.Unsupported`.
+ */
+export type ToolRenderError = {
+  readonly capability: string
+  readonly reason: string
+}
+
+const userLocationWire = (loc: UserLocation): Record<string, unknown> => ({
+  type: "approximate",
+  ...(loc.city !== undefined && { city: loc.city }),
+  ...(loc.region !== undefined && { region: loc.region }),
+  ...(loc.country !== undefined && { country: loc.country }),
+  ...(loc.timezone !== undefined && { timezone: loc.timezone }),
+})
+
+const configToWire = Match.type<AnthropicToolConfig>().pipe(
+  Match.discriminatorsExhaustive("kind")({
+    web_search: (c): Record<string, unknown> => ({
+      type: c.type,
+      name: "web_search",
+      ...(c.maxUses !== undefined && { max_uses: c.maxUses }),
+      ...(c.allowedDomains !== undefined && { allowed_domains: c.allowedDomains }),
+      ...(c.blockedDomains !== undefined && { blocked_domains: c.blockedDomains }),
+      ...(c.userLocation !== undefined && { user_location: userLocationWire(c.userLocation) }),
+    }),
+    code_execution: (c): Record<string, unknown> => ({ type: c.type, name: "code_execution" }),
+  }),
+)
+
+const decodeConfig = Schema.decodeUnknownResult(AnthropicToolConfig)
+
+const renderOne = (
+  tool: Tool.ProviderTool<string, any, string, any>,
+): Result.Result<Record<string, unknown>, ToolRenderError> =>
+  tool.provider !== "anthropic"
+    ? Result.fail({
+        capability: `providerTool:${tool.provider}`,
+        reason: `tool "${tool.name}" is hosted by "${tool.provider}", not anthropic`,
+      })
+    : decodeConfig(tool.config).pipe(
+        Result.map(configToWire),
+        Result.mapError(
+          (): ToolRenderError => ({
+            capability: "providerTool",
+            reason: `unrecognized Anthropic provider tool config on "${tool.name}"`,
+          }),
+        ),
+      )
+
+/**
+ * Render a toolkit's Anthropic provider tools to native `tools` entries. Fails
+ * with a `ToolRenderError` on the first foreign or unrecognized tool rather
+ * than dropping it.
+ */
+export const renderProviderTools = (
+  tools: ReadonlyArray<Tool.ProviderTool<string, any, string, any>>,
+): Result.Result<ReadonlyArray<Record<string, unknown>>, ToolRenderError> =>
+  Result.all(tools.map(renderOne))

package/src/anthropicTools.test.ts

@@ -0,0 +1,147 @@
+import { Effect, Option, Result, Schema } from "effect"
+import * as Tool from "@effect-uai/core/Tool"
+import { descriptorsOf, providerToolsOf } from "@effect-uai/core/Tool"
+import { describe, expect, it } from "vitest"
+import { codeExecutionTool, renderProviderTools, webSearchTool } from "./AnthropicTools.js"
+import { accumulatorToTurn, buildRequestBody, emptyAccumulator } from "./codec.js"
+import { KnownProviderEvent, applyEvent } from "./streamEvents.js"
+
+const localTool = Tool.make({
+  name: "get_weather",
+  description: "Look up the weather.",
+  inputSchema: Tool.fromEffectSchema(Schema.Struct({ city: Schema.String })),
+  run: ({ city }) => Effect.succeed(`sunny in ${city}`),
+})
+
+const wireFor = (toolkit: Record<string, Tool.AnyTool>) =>
+  Result.getOrThrow(renderProviderTools(providerToolsOf(toolkit)))
+
+const functionWire = (toolkit: Record<string, Tool.AnyTool>) =>
+  descriptorsOf(toolkit).map((t) => ({
+    name: t.name,
+    description: t.description,
+    input_schema: t.inputSchema,
+  }))
+
+const buildWith = (
+  toolkit: Record<string, Tool.AnyTool>,
+  toolChoice: Option.Option<Record<string, unknown>> = Option.none(),
+) => {
+  const tools = [...functionWire(toolkit), ...wireFor(toolkit)]
+  return Result.getOrThrow(
+    buildRequestBody({
+      model: "claude-sonnet-4-5",
+      history: [{ type: "message", role: "user", content: [{ type: "input_text", text: "hi" }] }],
+      maxTokens: 1024,
+      temperature: Option.none(),
+      topP: Option.none(),
+      topK: Option.none(),
+      stopSequences: Option.none(),
+      thinking: Option.none(),
+      tools: tools.length > 0 ? Option.some(tools) : Option.none(),
+      toolChoice,
+      userId: Option.none(),
+      outputConfig: Option.none(),
+      cacheControl: Option.none(),
+    }),
+  )
+}
+
+describe("Anthropic provider tools", () => {
+  it("renders web_search to the native wire entry with options", () => {
+    const wire = wireFor({
+      web_search: webSearchTool({ maxUses: 3, allowedDomains: ["example.com"] }),
+    })
+    expect(wire).toEqual([
+      {
+        type: "web_search_20250305",
+        name: "web_search",
+        max_uses: 3,
+        allowed_domains: ["example.com"],
+      },
+    ])
+  })
+
+  it("renders code_execution to its native wire entry", () => {
+    expect(wireFor({ code_execution: codeExecutionTool })).toEqual([
+      { type: "code_execution_20250522", name: "code_execution" },
+    ])
+  })
+
+  it("emits both a custom tool and the native entry in the same tools array", () => {
+    const body = buildWith({ get_weather: localTool, web_search: webSearchTool() })
+    expect(body.tools).toEqual([
+      expect.objectContaining({ name: "get_weather" }),
+      { type: "web_search_20250305", name: "web_search" },
+    ])
+  })
+
+  it("omits tool_choice for a native-only request", () => {
+    const body = buildWith({ web_search: webSearchTool() })
+    expect(body.tools).toHaveLength(1)
+    expect(body.tool_choice).toBeUndefined()
+  })
+
+  it("fails on a foreign provider tool", () => {
+    const foreign = Tool.provider({
+      name: "google_search",
+      description: "Gemini grounding.",
+      inputSchema: Tool.noInput,
+      provider: "gemini",
+      config: { kind: "google_search" },
+    })
+    expect(Result.isFailure(renderProviderTools(providerToolsOf({ google_search: foreign })))).toBe(
+      true,
+    )
+  })
+
+  it("fails on an unrecognized config", () => {
+    const bogus = Tool.provider({
+      name: "mystery",
+      description: "Unknown Anthropic tool.",
+      inputSchema: Tool.noInput,
+      provider: "anthropic",
+      config: { kind: "telepathy" },
+    })
+    expect(Result.isFailure(renderProviderTools(providerToolsOf({ mystery: bogus })))).toBe(true)
+  })
+})
+
+describe("Anthropic hosted-tool response tolerance", () => {
+  it("does not decode a server_tool_use content block as a known event", () => {
+    const serverToolUse = {
+      type: "content_block_start",
+      index: 0,
+      content_block: { type: "server_tool_use", id: "srvtoolu_1", name: "web_search", input: {} },
+    }
+    const decoded = Schema.decodeUnknownResult(KnownProviderEvent)(serverToolUse)
+    // Fails to decode → the SSE layer synthesizes `_unknown`, which is ignored.
+    expect(Result.isFailure(decoded)).toBe(true)
+  })
+
+  it("builds the text turn when hosted-tool blocks arrive as _unknown", () => {
+    // Sequence: server_tool_use + web_search_tool_result blocks flow through as
+    // `_unknown` (no accumulator change); the assistant's text answer is a
+    // normal text block and survives into the turn.
+    const events = [
+      { type: "_unknown", raw: { type: "content_block_start", content_block: "server_tool_use" } },
+      { type: "content_block_start", index: 1, content_block: { type: "text", text: "" } },
+      {
+        type: "content_block_delta",
+        index: 1,
+        delta: { type: "text_delta", text: "Grounded answer." },
+      },
+      { type: "content_block_stop", index: 1 },
+      { type: "message_stop" },
+    ] as const
+    const acc = events.reduce(applyEvent, emptyAccumulator)
+    const turn = accumulatorToTurn(acc)
+    expect(turn.items).toEqual([
+      {
+        type: "message",
+        role: "assistant",
+        content: [{ type: "output_text", text: "Grounded answer." }],
+      },
+    ])
+  })
+})

package/src/codec.ts

@@ -324,6 +324,20 @@ export type ThinkingConfig = {
   readonly budget_tokens: number
 }
 
+/** Cache lifetime. `1h` writes cost 2x base input; `5m` costs 1.25x. */
+export type CacheTtl = "5m" | "1h"
+
+/**
+ * Request-level cache breakpoint. Anthropic applies it to the last cacheable
+ * block and moves it forward as the conversation grows, so the cached prefix
+ * (`tools` → `system` → `messages`) follows the conversation without the
+ * caller re-placing anything.
+ */
+export type CacheControl = {
+  readonly type: "ephemeral"
+  readonly ttl?: CacheTtl
+}
+
 export type RequestBody = {
   readonly model: string
   readonly messages: ReadonlyArray<RequestMessage>
@@ -338,6 +352,7 @@ export type RequestBody = {
   readonly tool_choice?: Record<string, unknown>
   readonly metadata?: { readonly user_id: string }
   readonly output_config?: Record<string, unknown>
+  readonly cache_control?: CacheControl
   readonly stream: true
 }
 
@@ -354,6 +369,7 @@ export const buildRequestBody = (params: {
   readonly toolChoice: Option.Option<Record<string, unknown>>
   readonly userId: Option.Option<string>
   readonly outputConfig: Option.Option<Record<string, unknown>>
+  readonly cacheControl: Option.Option<CacheControl>
 }): Result.Result<RequestBody, JsonParseError> =>
   pipe(
     groupedMessages(params.history),
@@ -402,6 +418,10 @@ export const buildRequestBody = (params: {
           onNone: () => ({}),
           onSome: (output_config) => ({ output_config }),
         }),
+        ...Option.match(params.cacheControl, {
+          onNone: () => ({}),
+          onSome: (cache_control) => ({ cache_control }),
+        }),
         stream: true,
       }),
     ),
@@ -503,23 +523,34 @@ export const setStopReason = (acc: Accumulator, reason: string): Accumulator =>
   stopReason: Option.some(reason),
 })
 
-const cachedFromWire = (wire: WireUsage): Option.Option<number> =>
-  Option.fromNullishOr(wire.cache_read_input_tokens)
-
+// Anthropic splits input across three billed buckets: `input_tokens`
+// (post-breakpoint), cache reads, and cache writes. All three are kept;
+// `input_tokens` is not the input total. Each field carries over from the
+// prior value since a streamed turn spreads usage across events (input +
+// cache on message_start, output_tokens on message_delta), so total_tokens is
+// summed from the accumulated buckets, not one event.
 export const mergeUsage = (acc: Accumulator, wire: WireUsage): Accumulator => {
-  const cached = cachedFromWire(wire)
+  const prev = acc.usage
+  const input_tokens = wire.input_tokens ?? prev.input_tokens
+  const output_tokens = wire.output_tokens ?? prev.output_tokens
+  const cached_tokens = wire.cache_read_input_tokens ?? prev.input_tokens_details?.cached_tokens
+  const cache_write_tokens =
+    wire.cache_creation_input_tokens ?? prev.input_tokens_details?.cache_write_tokens
+
+  const buckets = [input_tokens, cached_tokens, cache_write_tokens, output_tokens]
+  const total_tokens = buckets.every((v) => v === undefined)
+    ? undefined
+    : buckets.reduce<number>((sum, v) => sum + (v ?? 0), 0)
+
+  const details: Items.InputTokensDetails = {
+    ...(cached_tokens !== undefined && { cached_tokens }),
+    ...(cache_write_tokens !== undefined && { cache_write_tokens }),
+  }
   const usage: Items.Usage = {
-    ...acc.usage,
-    ...(wire.input_tokens !== undefined && { input_tokens: wire.input_tokens }),
-    ...(wire.output_tokens !== undefined && { output_tokens: wire.output_tokens }),
-    ...(wire.input_tokens !== undefined &&
-      wire.output_tokens !== undefined && {
-        total_tokens: wire.input_tokens + wire.output_tokens,
-      }),
-    ...Option.match(cached, {
-      onNone: () => ({}),
-      onSome: (cached_tokens) => ({ input_tokens_details: { cached_tokens } }),
-    }),
+    ...(input_tokens !== undefined && { input_tokens }),
+    ...(output_tokens !== undefined && { output_tokens }),
+    ...(total_tokens !== undefined && { total_tokens }),
+    ...(Object.keys(details).length > 0 && { input_tokens_details: details }),
   }
   return { ...acc, usage }
 }

package/src/index.ts

@@ -1,4 +1,5 @@
 export * as Anthropic from "./Anthropic.js"
+export * as AnthropicTools from "./AnthropicTools.js"
 export * as codec from "./codec.js"
 export * as streamEvents from "./streamEvents.js"
 export * from "./models.js"

package/src/usage.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest"
+import { type WireUsage, emptyAccumulator, mergeUsage } from "./codec.js"
+import { type ProviderEvent, applyEvent } from "./streamEvents.js"
+
+// A completed cached turn: input split across post-breakpoint tokens, cache
+// reads, and cache writes, all billed separately.
+const wire: WireUsage = {
+  input_tokens: 94,
+  output_tokens: 210,
+  cache_read_input_tokens: 31851,
+  cache_creation_input_tokens: 604,
+}
+
+describe("mergeUsage", () => {
+  it("keeps all three input buckets, not just cache reads", () => {
+    const usage = mergeUsage(emptyAccumulator, wire).usage
+    expect(usage.input_tokens).toBe(94)
+    expect(usage.input_tokens_details?.cached_tokens).toBe(31851)
+    expect(usage.input_tokens_details?.cache_write_tokens).toBe(604)
+  })
+
+  it("totals every input bucket plus output", () => {
+    const usage = mergeUsage(emptyAccumulator, wire).usage
+    expect(usage.total_tokens).toBe(94 + 31851 + 604 + 210)
+  })
+})
+
+describe("streamed usage", () => {
+  // Anthropic sends input + cache on message_start and the final output_tokens
+  // on message_delta. total_tokens must reflect the accumulated buckets, not
+  // the (input + initial output) figure frozen at message_start.
+  it("computes a non-stale total across message_start and message_delta", () => {
+    const start: ProviderEvent = {
+      type: "message_start",
+      message: {
+        usage: {
+          input_tokens: 94,
+          output_tokens: 1,
+          cache_read_input_tokens: 31851,
+          cache_creation_input_tokens: 604,
+        },
+      },
+    }
+    const delta: ProviderEvent = {
+      type: "message_delta",
+      delta: { stop_reason: "end_turn" },
+      usage: { output_tokens: 210 },
+    }
+    const usage = applyEvent(applyEvent(emptyAccumulator, start), delta).usage
+    expect(usage.output_tokens).toBe(210)
+    expect(usage.input_tokens_details?.cache_write_tokens).toBe(604)
+    expect(usage.total_tokens).toBe(94 + 31851 + 604 + 210)
+  })
+})