@rulvar/anthropic 1.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/index.d.ts

@@ -0,0 +1,125 @@
+import { CanonicalId, ChatEvent, ChatRequest, FinishInfo, ModelCaps, ProviderAdapter, Usage, WireError } from "@rulvar/core";
+
+//#region src/caps.d.ts
+interface AnthropicModelInfo {
+  caps: ModelCaps;
+  /**
+  * Wire thinking form: current models accept only adaptive; the
+  * enabled/budget form remains functional only on Opus 4.6 and Sonnet
+  * 4.6 (docs/04, section "Thinking and sampling parameters").
+  */
+  thinkingForm: "adaptive" | "enabled-budget";
+  /** Minimum cacheable prefix in tokens (docs/04, section "Prompt caching"). */
+  cacheMinTokens: number;
+}
+/** Static seed table; docs/04 section 4 names the current model set. */
+declare const ANTHROPIC_MODELS: Record<string, AnthropicModelInfo>;
+/**
+* Unknown Anthropic models are assumed current-generation: adaptive
+* thinking, native structured outputs, no sampling parameters. refreshCaps
+* corrects window/output figures from the live model list.
+*/
+declare function anthropicModelInfo(model: string): AnthropicModelInfo;
+//#endregion
+//#region src/adapter.d.ts
+/** pause_turn continuation cap (docs/06 Appendix A; docs/04, section 4.6). */
+declare const DEFAULT_PAUSE_TURN_MAX_CONTINUATIONS = 5;
+/** The client sub-surface the adapter consumes; injectable for tests. */
+interface AnthropicClientLike {
+  messages: {
+    create(params: Record<string, unknown>, opts?: {
+      signal?: AbortSignal;
+    }): Promise<unknown>;
+    countTokens(params: Record<string, unknown>): Promise<{
+      input_tokens: number;
+    }>;
+  };
+  models: {
+    list(params?: Record<string, unknown>): Promise<{
+      data: Array<Record<string, unknown>>;
+      has_more?: boolean;
+      last_id?: string;
+    }>;
+  };
+}
+interface AnthropicAdapterOptions {
+  apiKey?: string;
+  baseURL?: string;
+  /** Test seam: a preconstructed client; production uses @anthropic-ai/sdk. */
+  client?: AnthropicClientLike;
+}
+/**
+* Creates the first-class Anthropic adapter (id 'anthropic'). SDK
+* autoretries are disabled (max_retries 0): the core owns retries and
+* wall-clock (docs/04, section "Retries belong to the core").
+*/
+declare function anthropic(options?: AnthropicAdapterOptions): ProviderAdapter;
+//#endregion
+//#region src/wire.d.ts
+/** Bijective canonical-to-wire tool-call id map (docs/04, section 1.2). */
+declare class IdMap {
+  private readonly toWire;
+  private readonly toCanonical;
+  private readonly mint;
+  constructor(mint: () => CanonicalId);
+  canonicalFor(wireId: string): CanonicalId;
+  wireFor(canonicalId: CanonicalId): string;
+}
+type Block = Record<string, unknown>;
+/**
+* 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
+* (docs/04, sections 1.7 and 4.4).
+*/
+declare function buildAnthropicParams(req: ChatRequest, options: {
+  ids: IdMap;
+  maxOutputTokens: number;
+  thinkingForm: "adaptive" | "enabled-budget";
+}): Record<string, unknown>;
+/** Raw Messages API stream events, structurally typed. */
+type AnthropicStreamEvent = Record<string, unknown> & {
+  type: string;
+};
+interface MappedStop {
+  finish?: FinishInfo;
+  pauseTurn: boolean;
+}
+/**
+* The docs/04 section 4.7 stop-reason table. pause_turn never surfaces as
+* a canonical finish: the adapter continues internally.
+*/
+declare function mapStopReason(stopReason: string | null | undefined, stopDetails: Record<string, unknown> | null | undefined): MappedStop;
+/**
+* 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 (docs/04, sections 1.6 and 4.4).
+*/
+declare function normalizeAnthropicUsage(raw: Record<string, unknown> | undefined): Usage;
+interface TurnMapping {
+  events: ChatEvent[];
+  /** Assistant content blocks collected verbatim (pause_turn continuation). */
+  assistantContent: Block[];
+  pauseTurn: boolean;
+  finished: boolean;
+}
+/**
+* Maps one Messages API stream into ChatEvents. Emits an early usage event
+* from message_start (the input side is known immediately) and exactly one
+* terminal finish unless the turn paused (pause_turn) or errored.
+* `carryRetained` holds thinking blocks from earlier pause_turn
+* continuations of the same turn so the terminal finish ships the whole
+* turn's retention payload (docs/04, section 2.3, M4-T02).
+*/
+declare function mapAnthropicStream(stream: AsyncIterable<AnthropicStreamEvent>, ids: IdMap, emit: (event: ChatEvent) => void, options?: {
+  carryRetained?: Block[];
+}): Promise<TurnMapping>;
+/**
+* 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 (docs/04, section 4.9). Adapters never sleep internally.
+*/
+declare function anthropicErrorToWire(error: unknown): WireError;
+//#endregion
+export { ANTHROPIC_MODELS, type AnthropicAdapterOptions, type AnthropicClientLike, type AnthropicModelInfo, type AnthropicStreamEvent, DEFAULT_PAUSE_TURN_MAX_CONTINUATIONS, IdMap, type TurnMapping, anthropic, anthropicErrorToWire, anthropicModelInfo, buildAnthropicParams, mapAnthropicStream, mapStopReason, normalizeAnthropicUsage };

package/dist/index.js

@@ -0,0 +1,685 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { createCanonicalIdMinter, isStrictCompatibleSchema } from "@rulvar/core";
+//#region src/caps.ts
+const ALL_EFFORTS = [
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max"
+];
+function current(contextWindow, maxOutputTokens, pricing, cacheMinTokens) {
+	return {
+		caps: {
+			structuredOutput: "native",
+			supportsTemperature: false,
+			supportsParallelTools: true,
+			reasoningEfforts: ALL_EFFORTS,
+			contextWindow,
+			maxOutputTokens,
+			pricing: {
+				inputUsdPerMTok: pricing.in,
+				outputUsdPerMTok: pricing.out,
+				cacheReadUsdPerMTok: pricing.cacheRead,
+				cacheWriteUsdPerMTok: pricing.cacheWrite
+			}
+		},
+		thinkingForm: "adaptive",
+		cacheMinTokens
+	};
+}
+/** Static seed table; docs/04 section 4 names the current model set. */
+const ANTHROPIC_MODELS = {
+	"claude-fable-5": current(1e6, 128e3, {
+		in: 20,
+		out: 100,
+		cacheRead: 2,
+		cacheWrite: 25
+	}, 2048),
+	"claude-opus-4-8": current(4e5, 128e3, {
+		in: 12,
+		out: 60,
+		cacheRead: 1.2,
+		cacheWrite: 15
+	}, 4096),
+	"claude-opus-4-7": current(4e5, 64e3, {
+		in: 10,
+		out: 50,
+		cacheRead: 1,
+		cacheWrite: 12.5
+	}, 4096),
+	"claude-sonnet-5": current(4e5, 64e3, {
+		in: 3,
+		out: 15,
+		cacheRead: .3,
+		cacheWrite: 3.75
+	}, 2048),
+	"claude-opus-4-6": {
+		...current(2e5, 32e3, {
+			in: 15,
+			out: 75,
+			cacheRead: 1.5,
+			cacheWrite: 18.75
+		}, 4096),
+		thinkingForm: "enabled-budget"
+	},
+	"claude-sonnet-4-6": {
+		...current(2e5, 64e3, {
+			in: 3,
+			out: 15,
+			cacheRead: .3,
+			cacheWrite: 3.75
+		}, 2048),
+		thinkingForm: "enabled-budget"
+	}
+};
+/**
+* Unknown Anthropic models are assumed current-generation: adaptive
+* thinking, native structured outputs, no sampling parameters. refreshCaps
+* corrects window/output figures from the live model list.
+*/
+function anthropicModelInfo(model) {
+	const exact = ANTHROPIC_MODELS[model];
+	if (exact !== void 0) return exact;
+	for (const [name, info] of Object.entries(ANTHROPIC_MODELS)) if (model.startsWith(`${name}-`)) return info;
+	return current(4e5, 64e3, {
+		in: 10,
+		out: 50,
+		cacheRead: 1,
+		cacheWrite: 12.5
+	}, 4096);
+}
+//#endregion
+//#region src/wire.ts
+/**
+* Canonical-to-wire mapping for the July 2026 Anthropic Messages API
+* (M1-T12): request building (system split, tools with strict, the
+* output_config umbrella, adaptive thinking, cache_control compilation),
+* the SSE-to-ChatEvent stream mapper with pause_turn absorption, the full
+* stop-reason table, and usage normalization under the Usage invariant.
+*
+* Owning spec: docs/04-model-layer-spec.md, section "@rulvar/anthropic".
+* Pure functions; the adapter glue in adapter.ts owns the SDK client.
+*/
+/** Bijective canonical-to-wire tool-call id map (docs/04, section 1.2). */
+var IdMap = class {
+	toWire = /* @__PURE__ */ new Map();
+	toCanonical = /* @__PURE__ */ new Map();
+	mint;
+	constructor(mint) {
+		this.mint = mint;
+	}
+	canonicalFor(wireId) {
+		const existing = this.toCanonical.get(wireId);
+		if (existing !== void 0) return existing;
+		const canonical = this.mint();
+		this.toCanonical.set(wireId, canonical);
+		this.toWire.set(canonical, wireId);
+		return canonical;
+	}
+	wireFor(canonicalId) {
+		const existing = this.toWire.get(canonicalId);
+		if (existing !== void 0) return existing;
+		const wireId = `toolu_${canonicalId}`;
+		this.toWire.set(canonicalId, wireId);
+		this.toCanonical.set(wireId, canonicalId);
+		return wireId;
+	}
+};
+function cacheControl(ttl) {
+	return ttl === "1h" ? {
+		type: "ephemeral",
+		ttl: "1h"
+	} : { type: "ephemeral" };
+}
+/**
+* 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
+* (docs/04, sections 1.7 and 4.4).
+*/
+function buildAnthropicParams(req, options) {
+	const systemBlocks = [];
+	const messages = [];
+	for (const msg of req.messages) {
+		if (msg.role === "system") {
+			for (const part of msg.parts) if (part.type === "text") systemBlocks.push({
+				type: "text",
+				text: part.text
+			});
+			continue;
+		}
+		const content = [];
+		for (const part of msg.parts) switch (part.type) {
+			case "text":
+				content.push({
+					type: "text",
+					text: part.text
+				});
+				break;
+			case "image":
+				content.push({
+					type: "image",
+					source: typeof part.data === "string" && part.data.startsWith("http") ? {
+						type: "url",
+						url: part.data
+					} : {
+						type: "base64",
+						media_type: part.mediaType,
+						data: typeof part.data === "string" ? part.data : Buffer.from(part.data).toString("base64")
+					}
+				});
+				break;
+			case "tool-call":
+				content.push({
+					type: "tool_use",
+					id: options.ids.wireFor(part.id),
+					name: part.name,
+					input: part.args ?? {}
+				});
+				break;
+			case "tool-result":
+				content.push({
+					type: "tool_result",
+					tool_use_id: options.ids.wireFor(part.id),
+					content: typeof part.result === "string" ? part.result : JSON.stringify(part.result ?? null),
+					...part.isError === true ? { is_error: true } : {}
+				});
+				break;
+			case "provider-raw":
+				if (part.provider === "anthropic") content.push(part.block);
+				break;
+		}
+		messages.push({
+			role: msg.role === "tool" ? "user" : msg.role,
+			content
+		});
+	}
+	const params = {
+		model: req.model,
+		max_tokens: req.maxOutputTokens ?? options.maxOutputTokens,
+		messages
+	};
+	if (systemBlocks.length > 0) params.system = systemBlocks;
+	if (req.stopSequences !== void 0) params.stop_sequences = req.stopSequences;
+	if (req.tools !== void 0) {
+		params.tools = req.tools.map((tool) => ({
+			name: tool.name,
+			description: tool.description,
+			input_schema: tool.parameters,
+			...isStrictCompatibleSchema(tool.parameters) ? { strict: true } : {}
+		}));
+		if (req.toolChoice === "required") params.tool_choice = { type: "any" };
+		else if (typeof req.toolChoice === "object") params.tool_choice = {
+			type: "tool",
+			name: req.toolChoice.name
+		};
+		else if (req.toolChoice === "auto") params.tool_choice = { type: "auto" };
+		else if (req.toolChoice === "none") params.tool_choice = { type: "none" };
+	}
+	const anthropicOptions = req.providerOptions?.anthropic ?? {};
+	const outputConfig = {};
+	if (req.effort !== void 0) outputConfig.effort = req.effort;
+	if (req.schema !== void 0) outputConfig.format = {
+		type: "json_schema",
+		schema: req.schema
+	};
+	if (anthropicOptions.task_budget !== void 0) outputConfig.task_budget = anthropicOptions.task_budget;
+	if (Object.keys(outputConfig).length > 0) params.output_config = outputConfig;
+	if (anthropicOptions.thinking !== void 0) params.thinking = anthropicOptions.thinking;
+	else if (options.thinkingForm === "adaptive") {
+		const display = anthropicOptions.thinkingDisplay;
+		params.thinking = typeof display === "string" ? {
+			type: "adaptive",
+			display
+		} : { type: "adaptive" };
+	}
+	for (const key of [
+		"temperature",
+		"top_p",
+		"top_k"
+	]) if (anthropicOptions[key] !== void 0) params[key] = anthropicOptions[key];
+	applyCacheHint(params, req.cacheHint);
+	return params;
+}
+function applyCacheHint(params, hint) {
+	if (hint === void 0 || hint.breakpoints.length === 0) return;
+	const kept = hint.breakpoints.slice(-4);
+	const tools = params.tools;
+	const system = params.system;
+	const messages = params.messages;
+	for (const breakpoint of kept) {
+		const control = cacheControl(breakpoint.ttl);
+		if (breakpoint.after === "tools") {
+			const last = tools?.[tools.length - 1];
+			if (last !== void 0) last.cache_control = control;
+		} else if (breakpoint.after === "system") {
+			const last = system?.[system.length - 1];
+			if (last !== void 0) last.cache_control = control;
+		} else {
+			const content = messages[breakpoint.after.messageIndex]?.content;
+			const last = content?.[content.length - 1];
+			if (last !== void 0) last.cache_control = control;
+		}
+	}
+}
+/**
+* The docs/04 section 4.7 stop-reason table. pause_turn never surfaces as
+* a canonical finish: the adapter continues internally.
+*/
+function mapStopReason(stopReason, stopDetails) {
+	switch (stopReason) {
+		case "end_turn":
+		case "stop_sequence": return {
+			finish: { reason: "stop" },
+			pauseTurn: false
+		};
+		case "tool_use": return {
+			finish: { reason: "tool-calls" },
+			pauseTurn: false
+		};
+		case "max_tokens": return {
+			finish: { reason: "max-tokens" },
+			pauseTurn: false
+		};
+		case "model_context_window_exceeded": return {
+			finish: { reason: "context-window-exceeded" },
+			pauseTurn: false
+		};
+		case "refusal": return {
+			finish: {
+				reason: "refusal",
+				refusal: {
+					provider: "anthropic",
+					...stopDetails === null || stopDetails === void 0 ? {} : { stopDetails: {
+						...typeof stopDetails.type === "string" ? { type: stopDetails.type } : {},
+						...typeof stopDetails.category === "string" ? { category: stopDetails.category } : {},
+						...typeof stopDetails.explanation === "string" ? { explanation: stopDetails.explanation } : {}
+					} }
+				}
+			},
+			pauseTurn: false
+		};
+		case "pause_turn": return { pauseTurn: true };
+		default: return {
+			finish: { reason: "stop" },
+			pauseTurn: false
+		};
+	}
+}
+/**
+* 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 (docs/04, sections 1.6 and 4.4).
+*/
+function normalizeAnthropicUsage(raw) {
+	const input = typeof raw?.input_tokens === "number" ? raw.input_tokens : 0;
+	const output = typeof raw?.output_tokens === "number" ? raw.output_tokens : 0;
+	const cacheRead = typeof raw?.cache_read_input_tokens === "number" ? raw.cache_read_input_tokens : 0;
+	const cacheWrite = typeof raw?.cache_creation_input_tokens === "number" ? raw.cache_creation_input_tokens : 0;
+	return {
+		inputTokens: input + cacheRead + cacheWrite,
+		outputTokens: output,
+		cacheReadTokens: cacheRead,
+		cacheWriteTokens: cacheWrite
+	};
+}
+/**
+* Maps one Messages API stream into ChatEvents. Emits an early usage event
+* from message_start (the input side is known immediately) and exactly one
+* terminal finish unless the turn paused (pause_turn) or errored.
+* `carryRetained` holds thinking blocks from earlier pause_turn
+* continuations of the same turn so the terminal finish ships the whole
+* turn's retention payload (docs/04, section 2.3, M4-T02).
+*/
+async function mapAnthropicStream(stream, ids, emit, options) {
+	const mapping = {
+		events: [],
+		assistantContent: [],
+		pauseTurn: false,
+		finished: false
+	};
+	const push = (event) => {
+		mapping.events.push(event);
+		emit(event);
+	};
+	let usage = {
+		inputTokens: 0,
+		outputTokens: 0,
+		cacheReadTokens: 0,
+		cacheWriteTokens: 0
+	};
+	let stopReason;
+	let stopSequence;
+	let stopDetails;
+	let responseId;
+	const openBlocks = /* @__PURE__ */ new Map();
+	for await (const event of stream) switch (event.type) {
+		case "message_start": {
+			const message = event.message;
+			responseId = typeof message?.id === "string" ? message.id : void 0;
+			usage = normalizeAnthropicUsage(message?.usage);
+			push({
+				type: "usage",
+				usage: { ...usage }
+			});
+			break;
+		}
+		case "content_block_start": {
+			const index = event.index;
+			const block = event.content_block;
+			const type = block.type;
+			if (type === "tool_use") {
+				const wireId = block.id;
+				const canonicalId = ids.canonicalFor(wireId);
+				openBlocks.set(index, {
+					kind: "tool_use",
+					canonicalId,
+					json: "",
+					block: { ...block }
+				});
+				push({
+					type: "tool-call-start",
+					id: canonicalId,
+					name: block.name
+				});
+			} else if (type === "thinking" || type === "redacted_thinking") openBlocks.set(index, {
+				kind: "thinking",
+				json: "",
+				block: { ...block }
+			});
+			else if (type === "text") openBlocks.set(index, {
+				kind: "text",
+				json: "",
+				block: {
+					...block,
+					text: ""
+				}
+			});
+			else openBlocks.set(index, {
+				kind: "other",
+				json: "",
+				block: { ...block }
+			});
+			break;
+		}
+		case "content_block_delta": {
+			const index = event.index;
+			const delta = event.delta;
+			const open = openBlocks.get(index);
+			if (open === void 0) break;
+			if (delta.type === "text_delta") {
+				const text = delta.text;
+				open.block.text = `${open.block.text ?? ""}${text}`;
+				push({
+					type: "text-delta",
+					text
+				});
+			} else if (delta.type === "thinking_delta") {
+				const text = delta.thinking;
+				open.block.thinking = `${open.block.thinking ?? ""}${text}`;
+				push({
+					type: "reasoning-delta",
+					text
+				});
+			} else if (delta.type === "input_json_delta") {
+				const partial = delta.partial_json;
+				open.json += partial;
+				if (open.canonicalId !== void 0) push({
+					type: "tool-call-delta",
+					id: open.canonicalId,
+					argsTextDelta: partial
+				});
+			} else if (delta.type === "signature_delta") open.block.signature = `${open.block.signature ?? ""}${delta.signature}`;
+			break;
+		}
+		case "content_block_stop": {
+			const index = event.index;
+			const open = openBlocks.get(index);
+			if (open === void 0) break;
+			openBlocks.delete(index);
+			if (open.kind === "tool_use" && open.canonicalId !== void 0) {
+				let args = {};
+				try {
+					args = open.json === "" ? {} : JSON.parse(open.json);
+				} catch {
+					args = { __unparsed: open.json };
+				}
+				open.block.input = args;
+				push({
+					type: "tool-call-end",
+					id: open.canonicalId,
+					args
+				});
+			}
+			mapping.assistantContent.push(open.block);
+			break;
+		}
+		case "message_delta": {
+			const delta = event.delta;
+			if (typeof delta?.stop_reason === "string") stopReason = delta.stop_reason;
+			if (typeof delta?.stop_sequence === "string") stopSequence = delta.stop_sequence;
+			if (delta?.stop_details !== void 0 && delta.stop_details !== null) stopDetails = delta.stop_details;
+			const deltaUsage = event.usage;
+			if (typeof deltaUsage?.output_tokens === "number") usage = {
+				...usage,
+				outputTokens: deltaUsage.output_tokens
+			};
+			break;
+		}
+		case "message_stop": {
+			const mapped = mapStopReason(stopReason, stopDetails);
+			if (mapped.pauseTurn) {
+				mapping.pauseTurn = true;
+				return mapping;
+			}
+			const providerMetadata = { anthropic: {} };
+			const meta = providerMetadata.anthropic;
+			if (responseId !== void 0) meta.responseId = responseId;
+			if (stopSequence !== void 0) meta.stopSequence = stopSequence;
+			const retained = [...options?.carryRetained ?? [], ...mapping.assistantContent.filter((block) => block.type === "thinking" || block.type === "redacted_thinking")];
+			if (retained.length > 0) meta.retainedParts = retained;
+			push({
+				type: "finish",
+				finish: mapped.finish ?? { reason: "stop" },
+				usage,
+				providerMetadata
+			});
+			mapping.finished = true;
+			return mapping;
+		}
+		default: break;
+	}
+	return mapping;
+}
+/**
+* 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 (docs/04, section 4.9). Adapters never sleep internally.
+*/
+function anthropicErrorToWire(error) {
+	const record = error;
+	const status = typeof record.status === "number" ? record.status : void 0;
+	const message = typeof record.message === "string" ? record.message : String(error);
+	const headerGet = (name) => {
+		const headers = record.headers;
+		if (headers === void 0 || headers === null) return;
+		if (typeof headers.get === "function") return headers.get(name) ?? void 0;
+		return headers[name];
+	};
+	if (status === 429) {
+		const retryAfter = headerGet("retry-after");
+		const buckets = {};
+		for (const name of [
+			"x-ratelimit-limit-requests",
+			"x-ratelimit-remaining-requests",
+			"x-ratelimit-limit-input-tokens",
+			"x-ratelimit-remaining-input-tokens",
+			"x-ratelimit-limit-output-tokens",
+			"x-ratelimit-remaining-output-tokens"
+		]) {
+			const value = headerGet(name);
+			if (value !== void 0) buckets[name] = value;
+		}
+		return {
+			code: "agent",
+			message,
+			retryable: true,
+			data: {
+				kind: "rate-limit",
+				...retryAfter === void 0 ? {} : { retryAfterMs: Number(retryAfter) * 1e3 },
+				...Object.keys(buckets).length > 0 ? { buckets } : {},
+				status: 429
+			}
+		};
+	}
+	return {
+		code: "agent",
+		message,
+		retryable: status === void 0 || status === 529 || status >= 500,
+		data: {
+			kind: "transport",
+			...status === void 0 ? {} : { status }
+		}
+	};
+}
+//#endregion
+//#region src/adapter.ts
+/**
+* The @rulvar/anthropic ProviderAdapter (M1-T12): SDK glue over the pure
+* wire mapping, with pause_turn absorption, SDK autoretries disabled, and
+* refreshCaps from the capabilities-bearing model list.
+*
+* Owning spec: docs/04-model-layer-spec.md, section "@rulvar/anthropic".
+*/
+/** pause_turn continuation cap (docs/06 Appendix A; docs/04, section 4.6). */
+const DEFAULT_PAUSE_TURN_MAX_CONTINUATIONS = 5;
+/**
+* Creates the first-class Anthropic adapter (id 'anthropic'). SDK
+* autoretries are disabled (max_retries 0): the core owns retries and
+* wall-clock (docs/04, section "Retries belong to the core").
+*/
+function anthropic(options = {}) {
+	const client = options.client ?? new Anthropic({
+		...options.apiKey === void 0 ? {} : { apiKey: options.apiKey },
+		...options.baseURL === void 0 ? {} : { baseURL: options.baseURL },
+		maxRetries: 0
+	});
+	const ids = new IdMap(createCanonicalIdMinter());
+	const refreshed = /* @__PURE__ */ new Map();
+	function infoFor(model) {
+		const base = anthropicModelInfo(model);
+		const patch = refreshed.get(model);
+		if (patch === void 0) return base;
+		return {
+			...base,
+			caps: {
+				...base.caps,
+				...patch
+			}
+		};
+	}
+	return {
+		id: "anthropic",
+		provider: "anthropic",
+		caps(model) {
+			return infoFor(model).caps;
+		},
+		async refreshCaps() {
+			let afterId;
+			do {
+				const page = await client.models.list(afterId === void 0 ? {} : { after_id: afterId });
+				for (const model of page.data) {
+					const id = model.id;
+					if (typeof id !== "string") continue;
+					const patch = {};
+					if (typeof model.max_input_tokens === "number") patch.contextWindow = model.max_input_tokens;
+					if (typeof model.max_tokens === "number") patch.maxOutputTokens = model.max_tokens;
+					if (Object.keys(patch).length > 0) refreshed.set(id, patch);
+				}
+				afterId = page.has_more === true && typeof page.last_id === "string" ? page.last_id : void 0;
+			} while (afterId !== void 0);
+		},
+		async *stream(req, signal) {
+			const info = infoFor(req.model);
+			const pauseCap = typeof req.providerOptions?.anthropic?.pauseTurnMaxContinuations === "number" ? req.providerOptions.anthropic.pauseTurnMaxContinuations : 5;
+			let params = buildAnthropicParams(req, {
+				ids,
+				maxOutputTokens: info.caps.maxOutputTokens,
+				thinkingForm: info.thinkingForm
+			});
+			const pending = [];
+			let continuations = 0;
+			const carryRetained = [];
+			while (true) {
+				let stream;
+				try {
+					stream = await client.messages.create({
+						...params,
+						stream: true
+					}, signal === void 0 ? void 0 : { signal });
+				} catch (thrown) {
+					yield {
+						type: "error",
+						error: anthropicErrorToWire(thrown)
+					};
+					return;
+				}
+				let mapping;
+				try {
+					mapping = await mapAnthropicStream(stream, ids, (event) => pending.push(event), { carryRetained });
+				} catch (thrown) {
+					if (signal?.aborted === true) return;
+					yield {
+						type: "error",
+						error: anthropicErrorToWire(thrown)
+					};
+					return;
+				}
+				for (const event of pending) yield event;
+				pending.length = 0;
+				if (!mapping.pauseTurn) return;
+				carryRetained.push(...mapping.assistantContent.filter((block) => block.type === "thinking" || block.type === "redacted_thinking"));
+				continuations += 1;
+				if (continuations > pauseCap) {
+					yield {
+						type: "error",
+						error: {
+							code: "agent",
+							message: `pause_turn continuation cap (${pauseCap}) exceeded`,
+							retryable: true,
+							data: { kind: "transport" }
+						}
+					};
+					return;
+				}
+				const messages = params.messages;
+				params = {
+					...params,
+					messages: [...messages, {
+						role: "assistant",
+						content: mapping.assistantContent
+					}]
+				};
+			}
+		},
+		async countTokens(req) {
+			const info = infoFor(req.model);
+			const params = buildAnthropicParams(req, {
+				ids,
+				maxOutputTokens: info.caps.maxOutputTokens,
+				thinkingForm: info.thinkingForm
+			});
+			const body = {
+				model: params.model,
+				messages: params.messages
+			};
+			if (params.system !== void 0) body.system = params.system;
+			if (params.tools !== void 0) body.tools = params.tools;
+			return (await client.messages.countTokens(body)).input_tokens;
+		}
+	};
+}
+//#endregion
+export { ANTHROPIC_MODELS, DEFAULT_PAUSE_TURN_MAX_CONTINUATIONS, IdMap, anthropic, anthropicErrorToWire, anthropicModelInfo, buildAnthropicParams, mapAnthropicStream, mapStopReason, normalizeAnthropicUsage };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@rulvar/anthropic",
+  "version": "1.0.0",
+  "description": "rulvar first-class provider adapter over @anthropic-ai/sdk.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.110.0",
+    "@rulvar/core": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "tsdown": "^0.22.3",
+    "typescript": "~6.0.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/o-stepper/rulvar.git",
+    "directory": "packages/anthropic"
+  },
+  "homepage": "https://rulvar.com",
+  "bugs": {
+    "url": "https://github.com/o-stepper/rulvar/issues"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "pack-check": "publint --pack pnpm && attw --pack . --profile esm-only"
+  }
+}