@warlock.js/ai-anthropic 5.25.0 → 5.26.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to `@warlock.js/ai-anthropic` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.26.0 - 2026-09-30
+
+### Fixed
+
+- Adaptive Claude reasoning now maps `minimal` to `output_config.effort: "low"` and supports `xhigh` and `max`; budget-mode models map them to 1,024, 24,000, and 32,000 thinking tokens respectively.
+- Claude reasoning-token usage is now included in responses when the API reports it, including streamed responses.
+- Responses stopped because the model context window was exceeded now report a length finish reason.
+- **Behaviour change:** Reasoning now works on current Claude models. Claude Opus 4.7, 4.8, 5 and 5.5, Sonnet 5 and 5.5, Fable 5 and 5.1, and any model id the adapter does not recognise now get `thinking: { type: "adaptive" }` with `output_config.effort` (`low`, `medium` or `high`, taken from `reasoning.effort`; `medium` when only `reasoning.maxTokens` is given). Before, every model got `budget_tokens`, which these models reject with a 400. Claude Haiku 4.5, Opus 4.6, Sonnet 4.6 and older models keep the `budget_tokens` shape. The default `max_tokens` is unchanged in both modes.
+- **Behaviour change:** `temperature` is no longer sent to models released after Claude Opus 4.6 (the same adaptive-thinking models listed above), because they reject any value other than the default with a 400. Haiku 4.5, the 4.6 models and older models still receive it.
+- **Behaviour change:** Claude 5-series models (`claude-opus-5*`, `claude-sonnet-5*`, `claude-fable-5*`, `claude-mythos-5*`) are now recognised as vision-capable, so image attachments are no longer rejected for them.
+
+### Added
+
+- `thinkingMode: "adaptive" | "budget"` on `anthropic.model({ ... })` overrides the thinking shape inferred from the model name. Use it for gateway model ids that don't follow Anthropic's naming, or to move Opus/Sonnet 4.6 onto adaptive thinking. It also decides whether `temperature` is sent. The `AnthropicThinkingMode` type is exported.
+- `promptCaching: true` now enables Anthropic's request-level automatic cache placement when a call has no explicit cache breakpoint, so the longest reusable prefix is cached. `promptCacheTtl?: "5m" | "1h"` controls the TTL for automatic and explicit cache markers; omission keeps Anthropic's five-minute default.
+
 ## 5.25.0 - 2026-09-28
 
 ### Changed
@@ -55,6 +71,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Changed
 
 - Lockstep release maintenance and dependency refresh.
+
 ## 5.20.0 - 2026-09-24
 
 ### Changed

package/cjs/index.cjs

@@ -36,13 +36,22 @@ let _warlock_js_logger = require("@warlock.js/logger");
 * Model-name prefixes for Claude families that accept image input
 * (vision) on the Messages API.
 *
-* Every Claude 3, Claude 3.5/3.7, and Claude 4 family model is
+* Every Claude 3, Claude 3.5/3.7, Claude 4 and Claude 5 family model is
 * multimodal, so the list covers both the dotted legacy naming
 * (`claude-3-haiku-...`, `claude-3-5-sonnet-...`) and the current
 * `claude-<tier>-4-*` naming (`claude-opus-4-7`, `claude-sonnet-4-6`,
 * `claude-haiku-4-5`). Pre-3 families (`claude-2`, `claude-instant`)
 * are text-only and intentionally absent.
 *
+* The Claude 5 series is multimodal too (claude-api ref, cached
+* 2026-09-25): its vision examples use `claude-opus-5-5`; the models list
+* credits Claude Fable 5.1 with vision and Claude Sonnet 5 with
+* high-resolution vision; Claude Mythos 5.1 has "same capabilities" as
+* Fable 5.1. The tier-5 prefixes cover every 5.x release
+* (`claude-opus-5`, `claude-opus-5-5`, `claude-sonnet-5-5`,
+* `claude-fable-5-1`, …). Opus/Sonnet 4.6–4.8 are already covered by the
+* tier-4 prefixes.
+*
 * Matched as a prefix so dated variants (`claude-opus-4-20250514`) are
 * covered without listing every release tag. Devs can always override
 * per-model via `anthropic.model({ name, vision: true | false })` —
@@ -53,7 +62,11 @@ const VISION_CAPABLE_PREFIXES = [
 	"claude-4",
 	"claude-opus-4",
 	"claude-sonnet-4",
-	"claude-haiku-4"
+	"claude-haiku-4",
+	"claude-opus-5",
+	"claude-sonnet-5",
+	"claude-fable-5",
+	"claude-mythos-5"
 ];
 /**
 * Infer whether a given Claude model name supports vision based on the
@@ -72,19 +85,100 @@ function inferVisionCapability(modelName) {
 	return VISION_CAPABLE_PREFIXES.some((prefix) => normalized.startsWith(prefix));
 }
 
+//#endregion
+//#region ../ai-anthropic/src/thinking-mode.ts
+/**
+* Family prefixes that are budget-mode in their entirety — plain
+* `startsWith` match (dated and `-latest` variants included).
+*/
+const BUDGET_FAMILY_PREFIXES = [
+	"claude-3",
+	"claude-2",
+	"claude-instant",
+	"claude-haiku-4"
+];
+/**
+* Individual pre-4.7 releases in the `claude-<tier>-4-*` naming. Matched
+* as a release root: the id must equal the root or continue with a
+* separator that is not a new minor version number, so `claude-opus-4`
+* matches `claude-opus-4-20250514` but NOT `claude-opus-4-7`. Ids from the
+* installed SDK `Model` union (`messages.d.ts:795`) plus the 4.6 pair.
+*/
+const BUDGET_RELEASE_ROOTS = [
+	"claude-opus-4",
+	"claude-opus-4-0",
+	"claude-opus-4-1",
+	"claude-opus-4-5",
+	"claude-opus-4-6",
+	"claude-sonnet-4",
+	"claude-sonnet-4-0",
+	"claude-sonnet-4-5",
+	"claude-sonnet-4-6"
+];
+/**
+* A remainder that starts a new minor version (`-7`, `-10`) — used to
+* stop a release root from swallowing a later release of the same line.
+* Dates (`-20250514`) and tags (`-latest`, `-v1`) are not minor versions.
+*/
+const NEXT_MINOR_VERSION = /^-\d{1,2}(?!\d)/;
+function matchesReleaseRoot(name, root) {
+	if (!name.startsWith(root)) return false;
+	const rest = name.slice(root.length);
+	if (rest === "") return true;
+	return (rest.startsWith("-") || rest.startsWith("@")) && !NEXT_MINOR_VERSION.test(rest);
+}
+/**
+* Infer the thinking mode for a Claude model id. Budget for Haiku 4.5, the
+* 4.6 pair, and every older family; adaptive for everything else,
+* including unknown and future ids. Explicit per-model config
+* (`AnthropicModelConfig.thinkingMode`) always wins over this inference.
+*
+* @example
+* inferThinkingMode("claude-opus-5-5");  // → "adaptive"
+* inferThinkingMode("claude-haiku-4-5"); // → "budget"
+* inferThinkingMode("claude-opus-9");    // → "adaptive" (unknown → current API direction)
+*/
+function inferThinkingMode(modelName) {
+	const normalized = modelName.toLowerCase();
+	if (BUDGET_FAMILY_PREFIXES.some((prefix) => normalized.startsWith(prefix))) return "budget";
+	if (BUDGET_RELEASE_ROOTS.some((root) => matchesReleaseRoot(normalized, root))) return "budget";
+	return "adaptive";
+}
+/**
+* Whether a model of this thinking mode accepts an explicit `temperature`.
+*
+* Installed SDK, `MessageCreateParamsBase.temperature`
+* (`messages.d.ts:2036-2040`): "Models released after Claude Opus 4.6 do
+* not support setting temperature. A value of 1.0 will be accepted for
+* backwards compatibility, all other values will be rejected with a 400
+* error." The claude-api ref's per-model table agrees: sampling is
+* "Removed - 400" on Fable 5/5.1, Opus 5.5/5/4.8/4.7 and Sonnet 5, and
+* "Non-default values - 400" on Sonnet 5.5; "Allowed" on Opus 4.6,
+* Sonnet 4.6, Haiku 4.5 and older.
+*
+* That split is exactly the adaptive/budget split in the table above
+* (adaptive = released after Opus 4.6; budget = Opus 4.6 and earlier), so
+* the thinking mode doubles as the sampling-parameter classification.
+*/
+function acceptsTemperature(mode) {
+	return mode === "budget";
+}
+
 //#endregion
 //#region ../ai-anthropic/src/utils/map-stop-reason.ts
 const stopReasonMap = {
 	end_turn: "stop",
 	stop_sequence: "stop",
 	max_tokens: "length",
+	model_context_window_exceeded: "length",
 	tool_use: "tool_calls"
 };
 /**
 * Map Anthropic's `stop_reason` to the normalized `FinishReason` union.
 *
-* `end_turn` / `stop_sequence` are both natural stops. `max_tokens`
-* maps to `length`. `tool_use` maps to `tool_calls`. Everything else —
+* `end_turn` / `stop_sequence` are both natural stops. `max_tokens` and
+* `model_context_window_exceeded` map to `length`. `tool_use` maps to
+* `tool_calls`. Everything else —
 * `refusal` (policy intervention), `pause_turn` (incomplete
 * long-running turn), `null`, or any value a future API version adds —
 * falls through to `"error"` so the agent treats the trip as a
@@ -468,16 +562,45 @@ const DEFAULT_MAX_TOKENS = 4096;
 */
 const MIN_THINKING_BUDGET = 1024;
 /**
-* Map the neutral `ReasoningEffort` level to an Anthropic
-* `thinking.budget_tokens` value. Anthropic budgets reasoning by token
-* count (unlike OpenAI's opaque `reasoning_effort` enum), so the three
-* neutral levels translate to representative token budgets when the
-* caller doesn't pass an explicit `reasoning.maxTokens`.
+* Effort used when the caller asks for reasoning with only
+* `reasoning.maxTokens` and no `effort`. `"medium"` is what the adapter
+* has always assumed (the budget lookup fell back to
+* `EFFORT_THINKING_BUDGET.medium`), so adaptive models get the same tier.
+*/
+const DEFAULT_THINKING_EFFORT = "medium";
+/**
+* Map the neutral `ReasoningEffort` level to a thinking token count.
+*
+* - Budget-mode models: sent as `thinking.budget_tokens` when the caller
+*   doesn't pass an explicit `reasoning.maxTokens`.
+* - Both modes: reserved on top of `DEFAULT_MAX_TOKENS` when the caller
+*   sets no `maxTokens`, because thinking counts toward `max_tokens`
+*   (installed SDK `ThinkingConfigParam` docs, `messages.d.ts:1105`).
+*   Adaptive models therefore get the same `max_tokens` the budget path
+*   has always produced.
 */
 const EFFORT_THINKING_BUDGET = {
+	minimal: 1024,
 	low: 1024,
 	medium: 4096,
-	high: 12e3
+	high: 12e3,
+	xhigh: 24e3,
+	max: 32e3
+};
+/**
+* Map the neutral `ReasoningEffort` level to Anthropic's
+* `output_config.effort` for adaptive-mode models. The installed SDK
+* accepts `low | medium | high | xhigh | max` (`OutputConfig.effort`,
+* `messages.ts:2767`); map every supported value 1:1 and clamp `minimal` to
+* the nearest accepted value, `low`.
+*/
+const EFFORT_TO_OUTPUT_EFFORT = {
+	minimal: "low",
+	low: "low",
+	medium: "medium",
+	high: "high",
+	xhigh: "xhigh",
+	max: "max"
 };
 /**
 * Anthropic-backed implementation of `ModelContract`.
@@ -525,6 +648,7 @@ var AnthropicModel = class {
 		this.name = config.name;
 		this.provider = provider;
 		this.pricing = config.pricing;
+		this.thinkingMode = config.thinkingMode ?? inferThinkingMode(config.name);
 		this.capabilities = {
 			structuredOutput: config.structuredOutput ?? true,
 			vision: config.vision ?? inferVisionCapability(config.name),
@@ -604,6 +728,8 @@ var AnthropicModel = class {
 			for await (const event of stream) {
 				if (event.type === "message_start") {
 					usage.input = event.message.usage.input_tokens ?? 0;
+					const thinkingTokens = event.message.usage.output_tokens_details?.thinking_tokens;
+					if (thinkingTokens !== null && thinkingTokens !== void 0) usage.reasoningTokens = thinkingTokens;
 					const cacheRead = event.message.usage.cache_read_input_tokens;
 					if (cacheRead !== null && cacheRead !== void 0 && cacheRead > 0) usage.cachedTokens = cacheRead;
 					const cacheWrite = event.message.usage.cache_creation_input_tokens;
@@ -655,6 +781,8 @@ var AnthropicModel = class {
 				if (event.type === "message_delta") {
 					rawStopReason = event.delta.stop_reason ?? rawStopReason;
 					usage.output = event.usage.output_tokens ?? usage.output;
+					const thinkingTokens = event.usage.output_tokens_details?.thinking_tokens;
+					if (thinkingTokens !== null && thinkingTokens !== void 0) usage.reasoningTokens = thinkingTokens;
 					const cacheRead = event.usage.cache_read_input_tokens;
 					if (cacheRead !== null && cacheRead !== void 0 && cacheRead > 0) usage.cachedTokens = cacheRead;
 					const cacheWrite = event.usage.cache_creation_input_tokens;
@@ -683,9 +811,10 @@ var AnthropicModel = class {
 	* prompt out of `messages`, resolves `max_tokens` (required by
 	* Anthropic) with the documented default, and conditionally attaches
 	* temperature, tools, native structured output, extended thinking
-	* (`reasoning`), and a system-prompt cache breakpoint (`cacheControl`).
+	* (`reasoning`), and automatic or explicit prompt-cache control.
 	* Temperature is dropped when thinking is enabled, since Anthropic
-	* rejects the two together.
+	* rejects the two together, and always for adaptive-mode models, which
+	* reject any explicit temperature (see `acceptsTemperature`).
 	*/
 	buildParams(messages, options) {
 		const { system, messages: anthropicMessages } = toAnthropicMessages(messages);
@@ -693,17 +822,19 @@ var AnthropicModel = class {
 		const temperature = options?.temperature ?? this.config.temperature;
 		const configuredMaxTokens = options?.maxTokens ?? this.config.maxTokens;
 		const thinkingBudget = thinking.thinking?.type === "enabled" ? thinking.thinking.budget_tokens : void 0;
-		const maxTokens = configuredMaxTokens ?? (thinkingBudget !== void 0 ? thinkingBudget + DEFAULT_MAX_TOKENS : DEFAULT_MAX_TOKENS);
+		const maxTokens = configuredMaxTokens ?? (thinking.reservedTokens !== void 0 ? thinking.reservedTokens + DEFAULT_MAX_TOKENS : DEFAULT_MAX_TOKENS);
+		const sendTemperature = temperature !== void 0 && !thinking.thinking && acceptsTemperature(this.thinkingMode);
 		if (thinkingBudget !== void 0 && configuredMaxTokens !== void 0 && configuredMaxTokens <= thinkingBudget) throw new Error(`Anthropic maxTokens (${configuredMaxTokens}) must be greater than thinking budget_tokens (${thinkingBudget})`);
 		return {
 			model: this.name,
 			max_tokens: maxTokens,
 			messages: anthropicMessages,
+			...this.buildAutomaticCacheControl(options?.cacheControl),
 			...this.buildSystem(system, options?.cacheControl),
-			...temperature !== void 0 && !thinking.thinking ? { temperature } : {},
+			...sendTemperature ? { temperature } : {},
 			...this.buildTools(options?.tools),
-			...this.buildStructuredOutput(options?.responseSchema),
-			...thinking
+			...this.buildOutputConfig(options?.responseSchema, thinking.effort),
+			...thinking.thinking ? { thinking: thinking.thinking } : {}
 		};
 	}
 	/**
@@ -724,31 +855,66 @@ var AnthropicModel = class {
 		if (this.capabilities.promptCaching && breakpoints > 0) return { system: [{
 			type: "text",
 			text: system,
-			cache_control: { type: "ephemeral" }
+			cache_control: this.cacheControl()
 		}] };
 		return { system };
 	}
 	/**
-	* Translate the neutral `reasoning` option into Anthropic's
-	* `thinking` request field. Emitted only when the model declares the
-	* `reasoning` capability AND a reasoning option is supplied; otherwise
-	* returns an empty object so the caller can unconditionally spread it.
+	* Let Anthropic select the last cacheable block when caching is enabled
+	* without a caller-selected breakpoint. An explicit breakpoint remains
+	* authoritative, so the request-level form is deliberately omitted then.
+	*/
+	buildAutomaticCacheControl(cacheControl) {
+		const breakpoints = cacheControl?.breakpoints ?? 0;
+		return this.config.promptCaching && breakpoints <= 0 ? { cache_control: this.cacheControl() } : {};
+	}
+	/** Build a typed cache-control marker, omitting TTL for Anthropic's 5-minute default. */
+	cacheControl() {
+		return {
+			type: "ephemeral",
+			...this.config.promptCacheTtl ? { ttl: this.config.promptCacheTtl } : {}
+		};
+	}
+	/**
+	* Translate the neutral `reasoning` option into Anthropic's thinking
+	* settings, in the shape this model accepts (`thinkingMode`). Emitted
+	* only when the model declares the `reasoning` capability AND a
+	* reasoning option is supplied; otherwise returns an empty object.
+	*
+	* - Adaptive mode (Opus 4.7+, Sonnet 5+, Fable 5+, unknown ids):
+	*   `thinking: { type: "adaptive" }` (installed SDK
+	*   `ThinkingConfigAdaptive`, `messages.d.ts:1065`) plus
+	*   `output_config.effort` from the neutral effort, defaulting to
+	*   `"medium"`. `budget_tokens` is never sent — these models 400 on it
+	*   (claude-api ref). `reasoning.maxTokens` only sizes the default
+	*   `max_tokens` headroom.
+	* - Budget mode (Haiku 4.5, Opus/Sonnet 4.6, older):
+	*   `thinking: { type: "enabled", budget_tokens }`. An explicit
+	*   `reasoning.maxTokens` wins; otherwise the effort maps to a tiered
+	*   budget. `budget_tokens` must be ≥ 1024 (`ThinkingConfigEnabled`,
+	*   `messages.d.ts:1084`), so the budget is floored at that minimum.
 	*
-	* Budget resolution: an explicit `reasoning.maxTokens` wins; otherwise
-	* the neutral `effort` level maps to a tiered token budget. Anthropic
-	* requires `budget_tokens` ≥ 1024, so the budget is floored at that
-	* minimum. The neutral `effort: "none"` ("run without reasoning") maps
-	* to no `thinking` block at all — extended thinking is opt-in here.
+	* The neutral `effort: "none"` ("run without reasoning") maps to no
+	* `thinking` field at all in both modes.
 	*/
 	buildThinking(reasoning) {
 		if (!this.capabilities.reasoning || !reasoning) return {};
 		if (reasoning.effort === "none") return {};
 		if (reasoning.maxTokens === void 0 && reasoning.effort === void 0) return {};
-		const budget = reasoning.maxTokens ?? EFFORT_THINKING_BUDGET[reasoning.effort ?? "medium"];
-		return { thinking: {
-			type: "enabled",
-			budget_tokens: Math.max(MIN_THINKING_BUDGET, budget)
-		} };
+		const effort = reasoning.effort ?? DEFAULT_THINKING_EFFORT;
+		const budget = Math.max(MIN_THINKING_BUDGET, reasoning.maxTokens ?? EFFORT_THINKING_BUDGET[effort]);
+		if (this.thinkingMode === "adaptive") return {
+			thinking: { type: "adaptive" },
+			effort: EFFORT_TO_OUTPUT_EFFORT[effort],
+			reservedTokens: budget
+		};
+		return {
+			thinking: {
+				type: "enabled",
+				budget_tokens: budget
+			},
+			reservedTokens: budget
+		};
 	}
 	/**
 	* Spread-friendly tools fragment. Returns an empty object when no
@@ -768,32 +934,49 @@ var AnthropicModel = class {
 		if (!mapped) return {};
 		if (this.config.promptCaching && mapped.length > 0) {
 			const last = mapped.length - 1;
-			mapped[last] = {
-				...mapped[last],
-				cache_control: { type: "ephemeral" }
+			const lastTool = mapped[last];
+			if (lastTool) mapped[last] = {
+				...lastTool,
+				cache_control: this.cacheControl()
 			};
 		}
 		return { tools: mapped };
 	}
 	/**
+	* Spread-friendly `output_config` fragment carrying both the native
+	* structured-output `format` and the adaptive-thinking `effort`, merged
+	* into one object (both live under `OutputConfig`, installed SDK
+	* `messages.d.ts:796-806`). Returns an empty object when neither applies,
+	* so budget-mode requests carry `output_config` only when a schema asks
+	* for it.
+	*/
+	buildOutputConfig(responseSchema, effort) {
+		const format = this.buildStructuredOutputFormat(responseSchema);
+		if (!format && !effort) return {};
+		return { output_config: {
+			...format ? { format } : {},
+			...effort ? { effort } : {}
+		} };
+	}
+	/**
 	* Translate the neutral `responseSchema` option into Anthropic's
 	* native `output_config.format` (JSON-schema structured outputs).
 	*
-	* Only emitted when the model declares the `structuredOutput`
+	* Only returned when the model declares the `structuredOutput`
 	* capability AND the schema is a proper root-object JSON Schema —
 	* Anthropic rejects non-object roots. When the capability is off
-	* (config override) or the schema is non-object, returns an empty
-	* object: the agent has already injected a soft schema hint into the
-	* system prompt as the fallback, and client-side `validate()` still
-	* enforces shape.
+	* (config override) or the schema is non-object, returns `undefined`:
+	* the agent has already injected a soft schema hint into the system
+	* prompt as the fallback, and client-side `validate()` still enforces
+	* shape.
 	*/
-	buildStructuredOutput(responseSchema) {
-		if (!responseSchema || !this.capabilities.structuredOutput) return {};
-		if (responseSchema.type !== "object" || typeof responseSchema.properties !== "object") return {};
-		return { output_config: { format: {
+	buildStructuredOutputFormat(responseSchema) {
+		if (!responseSchema || !this.capabilities.structuredOutput) return;
+		if (responseSchema.type !== "object" || typeof responseSchema.properties !== "object") return;
+		return {
 			type: "json_schema",
 			schema: responseSchema
-		} } };
+		};
 	}
 	/**
 	* Concatenate every `text` content block into the single neutral
@@ -833,24 +1016,24 @@ var AnthropicModel = class {
 	* Anthropic reports `input_tokens` / `output_tokens` separately with
 	* no pre-summed total, so `total` is computed. Cache-read tokens are
 	* surfaced as `cachedTokens` and cache-write tokens as
-	* `cacheWriteTokens`, each only when non-zero.
-	*
-	* Note: Anthropic does not report a separate reasoning-token count —
-	* extended-thinking tokens are billed inside `output_tokens` — so
-	* `Usage.reasoningTokens` is intentionally left unset here. Populating
-	* it would double-count against `output`.
+	* `cacheWriteTokens`, each only when non-zero. Anthropic also reports
+	* `output_tokens_details.thinking_tokens` as the reasoning subset of
+	* its inclusive `output_tokens`; it is surfaced as `reasoningTokens`
+	* when present, without changing the billing total.
 	*/
 	extractUsage(raw) {
 		const input = raw.input_tokens ?? 0;
 		const output = raw.output_tokens ?? 0;
 		const cacheRead = raw.cache_read_input_tokens;
 		const cacheWrite = raw.cache_creation_input_tokens;
+		const thinkingTokens = raw.output_tokens_details?.thinking_tokens;
 		return {
 			input,
 			output,
 			total: input + output,
 			...cacheRead !== null && cacheRead !== void 0 && cacheRead > 0 ? { cachedTokens: cacheRead } : {},
-			...cacheWrite !== null && cacheWrite !== void 0 && cacheWrite > 0 ? { cacheWriteTokens: cacheWrite } : {}
+			...cacheWrite !== null && cacheWrite !== void 0 && cacheWrite > 0 ? { cacheWriteTokens: cacheWrite } : {},
+			...thinkingTokens !== null && thinkingTokens !== void 0 ? { reasoningTokens: thinkingTokens } : {}
 		};
 	}
 	/**