@hiper2d/ai-agents 0.32.0 → 0.33.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.mjs CHANGED
@@ -2872,22 +2872,29 @@ ${instruction}`);
2872
2872
 
2873
2873
  // src/agents/anthropic-agent.ts
2874
2874
  import { Anthropic } from "@anthropic-ai/sdk";
2875
+ var CACHE_WRITE_MULTIPLIER = { "5m": 1.25, "1h": 2 };
2875
2876
  var rejectsDisabledThinking = (model) => model.includes("fable") || model.includes("opus-5-5");
2876
2877
  var usesBetweenToolsForOff = (model) => model.includes("sonnet-5-5");
2877
2878
  var usesAdaptiveThinking = (model) => !model.includes("haiku-4");
2878
2879
  var ClaudeAgent = class extends AbstractAgent {
2879
2880
  client;
2880
2881
  /**
2881
- * TTL for every breakpoint this agent places (system tiers and the message anchor).
2882
- * Anthropic bills a 5m write at 1.25x input, a 1h write at 2x, reads at 0.1x, and a read
2883
- * refreshes the timer on either TTL. Default '1h' because the main consumer runs at human
2884
- * pace: consecutive calls for one agent measured 12-78 minutes apart, so 5m entries
2885
- * expired before they were ever read (0-16% hit rate over 30 days, hits only on gaps
2886
- * under five minutes). Set '5m' for continuous traffic where every call lands inside the
2887
- * window; there the cheaper write wins. One knob for all breakpoints on purpose: Anthropic
2882
+ * TTL for every breakpoint this agent places (system tiers and the message anchor), or
2883
+ * 'off' to place none. Anthropic bills a 5m write at 1.25x input, a 1h write at 2x, reads
2884
+ * at 0.1x, and a read refreshes the timer on either TTL; with no breakpoint every token is
2885
+ * plain 1x input (Claude has no implicit caching). Caching pays only when enough of what
2886
+ * is written gets read back: break-even is ~22% of the prompt read at 5m and ~53% at 1h.
2887
+ * Measured on Werewolf (human-paced, consecutive calls for one bot 12-78 minutes apart):
2888
+ * 5m read 0-16% back, 1h 42-43% over 30 days of production bot turns (2026-11-06) — both
2889
+ * cost more than no cache, so that host sets 'off'. Default '1h' for continuous traffic
2890
+ * where calls land inside the window. One knob for all breakpoints on purpose: Anthropic
2888
2891
  * requires 1h entries to precede 5m ones, and a single TTL keeps that trivially true.
2889
2892
  */
2890
2893
  cacheTtl = "1h";
2894
+ /** The cache_control to attach to a breakpoint, or none when caching is off. */
2895
+ get cacheControl() {
2896
+ return this.cacheTtl === "off" ? {} : { cache_control: { type: "ephemeral", ttl: this.cacheTtl } };
2897
+ }
2891
2898
  // System-prompt breakpoints, one per cache tier (see CACHE_TIER_MARKER):
2892
2899
  // block 1 - shared static rules, byte-identical across all bots and games with the
2893
2900
  // same rule set. Caches are scoped per model, so one entry serves every bot
@@ -2903,7 +2910,7 @@ var ClaudeAgent = class extends AbstractAgent {
2903
2910
  get defaultParams() {
2904
2911
  return {
2905
2912
  max_tokens: this.maxOutputTokens,
2906
- system: this.instructionParts.map((part) => ({ type: "text", text: part, cache_control: { type: "ephemeral", ttl: this.cacheTtl } })),
2913
+ system: this.instructionParts.map((part) => ({ type: "text", text: part, ...this.cacheControl })),
2907
2914
  model: this.model
2908
2915
  };
2909
2916
  }
@@ -3002,6 +3009,9 @@ var ClaudeAgent = class extends AbstractAgent {
3002
3009
  * which for us is exactly the never-repeated tail — every entry it wrote would be dead.
3003
3010
  */
3004
3011
  applyCacheBreakpoint(messages) {
3012
+ if (this.cacheTtl === "off") {
3013
+ return;
3014
+ }
3005
3015
  if (messages.length < 2) {
3006
3016
  return;
3007
3017
  }
@@ -3024,9 +3034,11 @@ var ClaudeAgent = class extends AbstractAgent {
3024
3034
  * Builds TokenUsage from the response. Anthropic's input_tokens EXCLUDES cached tokens
3025
3035
  * (total prompt = input_tokens + cache_read + cache_creation), unlike the OpenAI-shaped
3026
3036
  * providers whose prompt_tokens include them — so reconstruct the full prompt size here
3027
- * before pricing. Cache reads bill at the cacheHitPrice (~0.1x); cache writes bill at
3028
- * 1.25x input, which MODEL_PRICING doesn't model, so written tokens are priced at the
3029
- * plain input rate (~20% undercount on the written span only).
3037
+ * before pricing. Cache reads bill at the cacheHitPrice (~0.1x). Cache writes bill at a
3038
+ * multiple of input by TTL (1.25x for 5m, 2x for 1h); MODEL_PRICING has no write rate, so
3039
+ * the premium is added on top at the call's effective input rate (which keeps any
3040
+ * long-context tier). Until 0.33.0 writes were priced at plain input, under-reporting
3041
+ * every 1h write by half.
3030
3042
  */
3031
3043
  buildTokenUsage(usage) {
3032
3044
  const cacheReadTokens = usage.cache_read_input_tokens ?? 0;
@@ -3034,7 +3046,14 @@ var ClaudeAgent = class extends AbstractAgent {
3034
3046
  const uncachedInputTokens = usage.input_tokens || 0;
3035
3047
  const inputTokens = uncachedInputTokens + cacheReadTokens + cacheWriteTokens;
3036
3048
  const outputTokens = usage.output_tokens || 0;
3037
- const cost = calculateAnthropicCost(this.model, inputTokens, outputTokens, cacheReadTokens);
3049
+ let cost = calculateAnthropicCost(this.model, inputTokens, outputTokens, cacheReadTokens);
3050
+ if (cacheWriteTokens > 0) {
3051
+ const byTtl = usage.cache_creation;
3052
+ const written1h = byTtl ? byTtl.ephemeral_1h_input_tokens ?? 0 : this.cacheTtl === "1h" ? cacheWriteTokens : 0;
3053
+ const written5m = byTtl ? byTtl.ephemeral_5m_input_tokens ?? 0 : cacheWriteTokens - written1h;
3054
+ const inputRate = inputTokens > 0 ? calculateAnthropicCost(this.model, inputTokens, 0, 0) / inputTokens : 0;
3055
+ cost += inputRate * (written1h * (CACHE_WRITE_MULTIPLIER["1h"] - 1) + written5m * (CACHE_WRITE_MULTIPLIER["5m"] - 1));
3056
+ }
3038
3057
  if (cacheReadTokens > 0 || cacheWriteTokens > 0) {
3039
3058
  this.logger(`\u{1F4BE} Prompt cache: ${cacheReadTokens} read, ${cacheWriteTokens} written, ${uncachedInputTokens} uncached`);
3040
3059
  }
@@ -3043,8 +3062,9 @@ var ClaudeAgent = class extends AbstractAgent {
3043
3062
  outputTokens,
3044
3063
  totalTokens: inputTokens + outputTokens,
3045
3064
  costUSD: cost,
3046
- // Cache reads only — writes are a billing premium, not reuse of prior context.
3047
- ...cacheReadTokens > 0 ? { cachedInputTokens: cacheReadTokens } : {}
3065
+ // Breakdowns of inputTokens, omitted when zero (Firestore rejects undefined).
3066
+ ...cacheReadTokens > 0 ? { cachedInputTokens: cacheReadTokens } : {},
3067
+ ...cacheWriteTokens > 0 ? { cacheWriteTokens } : {}
3048
3068
  };
3049
3069
  }
3050
3070
  convertRole(role) {