@kindgi/adapter-model-anthropic 0.0.0-bootstrap.0 → 0.1.0

package/dist/translate.d.ts

@@ -0,0 +1,64 @@
+import type Anthropic from '@anthropic-ai/sdk';
+import type { ModelCallResult, ModelMessage, ModelToolDefinition } from '@kindgi/capabilities';
+/**
+ * The framework's tool id convention is `<pack>.<tool>` — e.g.
+ * `acme.orders.lookup`. Anthropic's Messages API rejects tool
+ * names that don't match `^[a-zA-Z0-9_-]{1,128}$` (in particular,
+ * dots are forbidden), so this adapter transparently encodes tool
+ * names on the way out and decodes them on the way in.
+ *
+ * Encoding is a simple `.` → `__` substitution. Reversible as long
+ * as authors don't put literal `__` in their tool ids — which the
+ * framework's kebab-case convention already discourages. The
+ * substitution is contained to the wire boundary; the message trail,
+ * runtime registry, and provenance records all continue to see the
+ * canonical `<pack>.<tool>` form.
+ */
+export declare function encodeToolName(name: string): string;
+export declare function decodeToolName(name: string): string;
+/**
+ * Translate a framework message trail to the Anthropic Messages API
+ * shape. Two structural mappings matter:
+ *
+ *   - `role: 'system'` messages lift out of the message array into
+ *     Anthropic's top-level `system` parameter. Multiple system
+ *     messages concatenate with a blank-line separator, preserving
+ *     order — the framework's message-trail contract lets any handler
+ *     push a system message, so we don't assume there's only one.
+ *   - `role: 'tool'` messages fold into `role: 'user'` messages
+ *     carrying `tool_result` content blocks. Anthropic requires tool
+ *     results to arrive as user turns; consecutive tool results
+ *     merge into a single user message (matching the framework's
+ *     dispatch-tools handler which appends one tool message per call
+ *     after an assistant `tool_use` turn).
+ */
+export declare function toAnthropicMessages(messages: readonly ModelMessage[]): {
+    readonly system: string | undefined;
+    readonly messages: readonly Anthropic.MessageParam[];
+};
+/**
+ * Translate framework tool definitions to Anthropic's `tools` shape.
+ * `input_schema` is JSON-Schema-shaped on both sides — direct passthrough.
+ */
+export declare function toAnthropicTools(tools: readonly ModelToolDefinition[]): readonly Anthropic.Tool[];
+/**
+ * Translate an Anthropic response message back into a framework
+ * `ModelMessage`. Text blocks concatenate into `content`; tool_use
+ * blocks become `toolCalls`. Thinking blocks are ignored (the
+ * framework has no thinking field on `ModelMessage`).
+ */
+export declare function fromAnthropicResponse(response: Anthropic.Message): ModelMessage;
+/**
+ * Map Anthropic's `stop_reason` to the framework's `finishReason`.
+ *
+ * Mapping choices:
+ *   - `end_turn`, `stop_sequence`, `pause_turn` → `stop`
+ *     (`pause_turn` is a server-side agentic pause — non-streaming
+ *     invokers don't resume, so treat as terminal for this call.)
+ *   - `max_tokens` → `length`
+ *   - `tool_use` → `tool-use`
+ *   - `refusal` → `content-filter`
+ *   - `null` (streaming edge) / unknown → `stop`
+ */
+export declare function mapStopReason(reason: Anthropic.Message['stop_reason']): ModelCallResult['finishReason'];
+//# sourceMappingURL=translate.d.ts.map

package/dist/translate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translate.d.ts","sourceRoot":"","sources":["../src/translate.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,SAAS,MAAM,mBAAmB,CAAC;AAE/C,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EAEZ,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,GAAG;IACtE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,SAAS,SAAS,CAAC,YAAY,EAAE,CAAC;CACtD,CAmDA;AAsBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,GAAG,SAAS,SAAS,CAAC,IAAI,EAAE,CAMjG;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,SAAS,CAAC,OAAO,GAAG,YAAY,CAyB/E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,aAAa,CAAC,GACvC,eAAe,CAAC,cAAc,CAAC,CAejC"}

package/dist/translate.js

@@ -0,0 +1,175 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * The framework's tool id convention is `<pack>.<tool>` — e.g.
+ * `acme.orders.lookup`. Anthropic's Messages API rejects tool
+ * names that don't match `^[a-zA-Z0-9_-]{1,128}$` (in particular,
+ * dots are forbidden), so this adapter transparently encodes tool
+ * names on the way out and decodes them on the way in.
+ *
+ * Encoding is a simple `.` → `__` substitution. Reversible as long
+ * as authors don't put literal `__` in their tool ids — which the
+ * framework's kebab-case convention already discourages. The
+ * substitution is contained to the wire boundary; the message trail,
+ * runtime registry, and provenance records all continue to see the
+ * canonical `<pack>.<tool>` form.
+ */
+export function encodeToolName(name) {
+    return name.replace(/\./g, '__');
+}
+export function decodeToolName(name) {
+    return name.replace(/__/g, '.');
+}
+/**
+ * Translate a framework message trail to the Anthropic Messages API
+ * shape. Two structural mappings matter:
+ *
+ *   - `role: 'system'` messages lift out of the message array into
+ *     Anthropic's top-level `system` parameter. Multiple system
+ *     messages concatenate with a blank-line separator, preserving
+ *     order — the framework's message-trail contract lets any handler
+ *     push a system message, so we don't assume there's only one.
+ *   - `role: 'tool'` messages fold into `role: 'user'` messages
+ *     carrying `tool_result` content blocks. Anthropic requires tool
+ *     results to arrive as user turns; consecutive tool results
+ *     merge into a single user message (matching the framework's
+ *     dispatch-tools handler which appends one tool message per call
+ *     after an assistant `tool_use` turn).
+ */
+export function toAnthropicMessages(messages) {
+    const systemParts = [];
+    const out = [];
+    for (const msg of messages) {
+        if (msg.role === 'system') {
+            if (msg.content.length > 0)
+                systemParts.push(msg.content);
+            continue;
+        }
+        if (msg.role === 'user') {
+            appendToUserTurn(out, [{ type: 'text', text: msg.content }]);
+            continue;
+        }
+        if (msg.role === 'assistant') {
+            const blocks = [];
+            if (msg.content.length > 0)
+                blocks.push({ type: 'text', text: msg.content });
+            if (msg.toolCalls !== undefined) {
+                for (const tc of msg.toolCalls) {
+                    blocks.push({
+                        type: 'tool_use',
+                        id: tc.id,
+                        // Encode when replaying prior assistant turns — the
+                        // message trail stores canonical framework names, but
+                        // Anthropic on the wire wants the encoded form.
+                        name: encodeToolName(tc.name),
+                        input: tc.arguments,
+                    });
+                }
+            }
+            // Anthropic rejects assistant turns with empty content — skip
+            // rather than emit an invalid message. The framework's
+            // dispatch-tools handler ensures either text or tool_use is
+            // present, so this only triggers on malformed input.
+            if (blocks.length > 0) {
+                out.push({ role: 'assistant', content: blocks });
+            }
+            continue;
+        }
+        // role === 'tool'
+        const toolResult = {
+            type: 'tool_result',
+            tool_use_id: msg.toolCallId ?? '',
+            content: msg.content,
+        };
+        appendToUserTurn(out, [toolResult]);
+    }
+    return {
+        system: systemParts.length > 0 ? systemParts.join('\n\n') : undefined,
+        messages: out,
+    };
+}
+function appendToUserTurn(out, blocks) {
+    const last = out[out.length - 1];
+    if (last !== undefined && last.role === 'user') {
+        const existing = normalizeContent(last.content);
+        last.content = [...existing, ...blocks];
+        return;
+    }
+    out.push({ role: 'user', content: [...blocks] });
+}
+function normalizeContent(content) {
+    if (typeof content === 'string')
+        return [{ type: 'text', text: content }];
+    return [...content];
+}
+/**
+ * Translate framework tool definitions to Anthropic's `tools` shape.
+ * `input_schema` is JSON-Schema-shaped on both sides — direct passthrough.
+ */
+export function toAnthropicTools(tools) {
+    return tools.map((t) => ({
+        name: encodeToolName(t.name),
+        description: t.description,
+        input_schema: t.inputSchema,
+    }));
+}
+/**
+ * Translate an Anthropic response message back into a framework
+ * `ModelMessage`. Text blocks concatenate into `content`; tool_use
+ * blocks become `toolCalls`. Thinking blocks are ignored (the
+ * framework has no thinking field on `ModelMessage`).
+ */
+export function fromAnthropicResponse(response) {
+    const textParts = [];
+    const toolCalls = [];
+    for (const block of response.content) {
+        if (block.type === 'text') {
+            textParts.push(block.text);
+        }
+        else if (block.type === 'tool_use') {
+            toolCalls.push({
+                id: block.id,
+                // Decode: Anthropic returns the encoded name (`weather__forecast`);
+                // the rest of the framework expects the canonical dotted form.
+                name: decodeToolName(block.name),
+                arguments: (block.input ?? {}),
+            });
+        }
+        // 'thinking' / 'redacted_thinking' blocks are ignored (see above).
+    }
+    const message = {
+        role: 'assistant',
+        content: textParts.join(''),
+        ...(toolCalls.length > 0 && { toolCalls }),
+    };
+    return message;
+}
+/**
+ * Map Anthropic's `stop_reason` to the framework's `finishReason`.
+ *
+ * Mapping choices:
+ *   - `end_turn`, `stop_sequence`, `pause_turn` → `stop`
+ *     (`pause_turn` is a server-side agentic pause — non-streaming
+ *     invokers don't resume, so treat as terminal for this call.)
+ *   - `max_tokens` → `length`
+ *   - `tool_use` → `tool-use`
+ *   - `refusal` → `content-filter`
+ *   - `null` (streaming edge) / unknown → `stop`
+ */
+export function mapStopReason(reason) {
+    switch (reason) {
+        case 'end_turn':
+        case 'stop_sequence':
+        case 'pause_turn':
+            return 'stop';
+        case 'max_tokens':
+            return 'length';
+        case 'tool_use':
+            return 'tool-use';
+        case 'refusal':
+            return 'content-filter';
+        default:
+            return 'stop';
+    }
+}
+//# sourceMappingURL=translate.js.map

package/dist/translate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"translate.js","sourceRoot":"","sources":["../src/translate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,51 @@
 {
   "name": "@kindgi/adapter-model-anthropic",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder so a trusted publisher can be attached. Releases are published from https://github.com/kindgi/kindgi-sdk with provenance; use 0.1.0 or later.",
+  "version": "0.1.0",
+  "description": "Anthropic ModelProvider for @kindgi/capabilities. Wraps @anthropic-ai/sdk with the framework's provider-neutral interface: message-trail ↔ Messages API translation, prompt-caching-aware cost accounting, and lazy API-key resolution so per-tenant registries can close over a SecretStore scope. Non-streaming, tool-use enabled. Wire per-tenant in the provider registry (see @kindgi/capabilities).",
   "license": "Apache-2.0",
-  "repository": { "type": "git", "url": "git+https://github.com/kindgi/kindgi-sdk.git" }
-}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kindgi/kindgi-sdk.git",
+    "directory": "packages/adapters/model-anthropic"
+  },
+  "homepage": "https://github.com/kindgi/kindgi-sdk/tree/main/packages/adapters/model-anthropic#readme",
+  "bugs": {
+    "url": "https://github.com/kindgi/kindgi-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@kindgi/capabilities": "0.1.0",
+    "@anthropic-ai/sdk": "^0.68.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}

package/src/cost.ts

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type Anthropic from '@anthropic-ai/sdk';
+
+/**
+ * Cost multipliers for prompt-cache tokens. Anthropic prices cache
+ * activity as a multiple of the base input rate:
+ *
+ *   - Cache creation (writing tokens to a new cache entry): 1.25x base
+ *     for the 5-minute TTL tier, 2x for the 1-hour tier.
+ *   - Cache read (reading tokens from an existing cache entry): 0.1x
+ *     base.
+ *
+ * Defaults below match the 5-minute tier — the framework's
+ * `ModelCallInput` doesn't distinguish TTLs, so callers using the
+ * 1-hour cache tier should override
+ * `promptCacheCreationMultiplier` at provider construction time.
+ */
+export const DEFAULT_CACHE_CREATION_MULTIPLIER_5MIN = 1.25;
+export const DEFAULT_CACHE_READ_MULTIPLIER = 0.1;
+
+export interface CostRates {
+  readonly promptUsdPer1kTokens: number;
+  readonly completionUsdPer1kTokens: number;
+  readonly promptCacheCreationMultiplier?: number;
+  readonly promptCacheReadMultiplier?: number;
+}
+
+/**
+ * Compute the USD cost of a single Anthropic invocation from the
+ * response's `usage` object.
+ *
+ * Anthropic reports four token counters:
+ *   - `input_tokens` — regular (uncached) input tokens
+ *   - `output_tokens` — completion tokens
+ *   - `cache_creation_input_tokens` — tokens WRITTEN to cache this
+ *     request (billed at `input * creationMultiplier`)
+ *   - `cache_read_input_tokens` — tokens READ from cache this request
+ *     (billed at `input * readMultiplier`)
+ *
+ * `input_tokens` already excludes cache-read + cache-creation counts,
+ * so we can sum the three input categories with their respective
+ * rates without double-counting.
+ */
+export function computeCostUsd(usage: Anthropic.Usage, rates: CostRates): number {
+  const inputRate = rates.promptUsdPer1kTokens;
+  const outputRate = rates.completionUsdPer1kTokens;
+  const creationMultiplier =
+    rates.promptCacheCreationMultiplier ?? DEFAULT_CACHE_CREATION_MULTIPLIER_5MIN;
+  const readMultiplier = rates.promptCacheReadMultiplier ?? DEFAULT_CACHE_READ_MULTIPLIER;
+
+  const inputTokens = usage.input_tokens;
+  const outputTokens = usage.output_tokens;
+  const cacheCreation = usage.cache_creation_input_tokens ?? 0;
+  const cacheRead = usage.cache_read_input_tokens ?? 0;
+
+  const inputCost =
+    (inputTokens * inputRate +
+      cacheCreation * inputRate * creationMultiplier +
+      cacheRead * inputRate * readMultiplier) /
+    1000;
+  const outputCost = (outputTokens * outputRate) / 1000;
+
+  return inputCost + outputCost;
+}
+
+/**
+ * Roll up Anthropic's four-way token split into the framework's
+ * `UsageCounters` shape.
+ *
+ *   - `promptTokens` = total tokens billed as input = regular +
+ *     cache-creation + cache-read.
+ *   - `completionTokens` = output tokens.
+ *   - `cachedTokens` = cache-read tokens (surfaced for observability;
+ *     the framework's cost meter uses `costUsd` directly, not this
+ *     field, so we don't need to bake cache math into `promptTokens`).
+ */
+export function toFrameworkUsage(usage: Anthropic.Usage): {
+  readonly promptTokens: number;
+  readonly completionTokens: number;
+  readonly cachedTokens?: number;
+} {
+  const cacheCreation = usage.cache_creation_input_tokens ?? 0;
+  const cacheRead = usage.cache_read_input_tokens ?? 0;
+  const promptTokens = usage.input_tokens + cacheCreation + cacheRead;
+  const base = {
+    promptTokens,
+    completionTokens: usage.output_tokens,
+  };
+  return cacheRead > 0 ? { ...base, cachedTokens: cacheRead } : base;
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+export { createAnthropicProvider } from './provider.js';
+export type { AnthropicModelInfo, AnthropicProviderOptions } from './provider.js';
+export {
+  DEFAULT_CACHE_CREATION_MULTIPLIER_5MIN,
+  DEFAULT_CACHE_READ_MULTIPLIER,
+  computeCostUsd,
+  toFrameworkUsage,
+} from './cost.js';
+export type { CostRates } from './cost.js';
+export {
+  fromAnthropicResponse,
+  mapStopReason,
+  toAnthropicMessages,
+  toAnthropicTools,
+} from './translate.js';
+export type { ModelProvider } from '@kindgi/capabilities';

package/src/provider.ts

@@ -0,0 +1,188 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import Anthropic from '@anthropic-ai/sdk';
+
+import type {
+  ModelCallInput,
+  ModelCallResult,
+  ModelInfo,
+  ModelProvider,
+  ProviderMetadata,
+} from '@kindgi/capabilities';
+
+import { computeCostUsd, toFrameworkUsage } from './cost.js';
+import {
+  fromAnthropicResponse,
+  mapStopReason,
+  toAnthropicMessages,
+  toAnthropicTools,
+} from './translate.js';
+
+/**
+ * Anthropic-specific `ModelInfo` extension. Widens the framework's
+ * `ModelInfo.cost` with the two Anthropic prompt-cache multipliers
+ * (`promptCacheCreationMultiplier`, `promptCacheReadMultiplier`) that
+ * `computeCostUsd` uses to bill cache activity per invocation.
+ *
+ * When either multiplier is omitted the framework falls back to
+ * Anthropic's 5-minute-tier defaults (1.25 / 0.1) inside `cost.ts`.
+ */
+export interface AnthropicModelInfo extends ModelInfo {
+  readonly cost: ModelInfo['cost'] & {
+    readonly promptCacheCreationMultiplier?: number;
+    readonly promptCacheReadMultiplier?: number;
+  };
+}
+
+/**
+ * Configuration for the Anthropic `ModelProvider`.
+ *
+ * `apiKey` accepts either a static string or a lazy resolver
+ * `() => Promise<string>`. The resolver form is what makes per-tenant
+ * BYO keys work: each tenant's `ModelProvider` instance is registered
+ * with a resolver that closes over that tenant's `SecretStore` scope
+ * plus the secret name. The adapter calls the resolver on every
+ * invocation, so rotating the underlying secret is transparent — the
+ * next call gets the new key.
+ *
+ * `metadata` follows the same pattern as the OpenAI-compat model
+ * adapter: caller-supplied, since Anthropic's API surface doesn't
+ * advertise pricing / context-window / features and pricing changes
+ * shouldn't force an adapter release. `models[]` is authoritative for
+ * routing; the adapter picks the right model at invoke time based on
+ * `ModelCallInput.model` (which must match one of `models[i].name`).
+ */
+export interface AnthropicProviderOptions {
+  readonly apiKey: string | (() => string | Promise<string>);
+  /**
+   * Metadata surfaced to the router. `models[]` MUST list every model
+   * the caller expects to invoke through this connection; the adapter
+   * uses `input.model` to pick the right entry per call. Per-model
+   * `cost` accepts Anthropic prompt-cache multipliers via
+   * `AnthropicModelInfo`.
+   */
+  readonly metadata: Omit<ProviderMetadata, 'models'> & {
+    readonly models: readonly AnthropicModelInfo[];
+  };
+  /** Override the base URL (proxy, gateway, region routing). */
+  readonly baseURL?: string;
+  /**
+   * Additional SDK client options (timeouts, custom fetch, headers,
+   * etc.). `apiKey` and `baseURL` from the top level always win.
+   */
+  readonly clientOptions?: Omit<ConstructorParameters<typeof Anthropic>[0], 'apiKey' | 'baseURL'>;
+  /**
+   * Dependency-injected SDK client. When present, `apiKey` /
+   * `baseURL` / `clientOptions` are ignored on construction (tests
+   * pass a mock; production wires a shared client if needed).
+   */
+  readonly client?: Anthropic;
+}
+
+/**
+ * Adapter-level fallback when neither `ModelCallInput.maxOutputTokens`
+ * nor the picked `ModelInfo.maxOutputTokens` is set. Anthropic requires
+ * `max_tokens` on every request.
+ */
+const DEFAULT_MAX_TOKENS = 4096;
+
+/**
+ * Create an Anthropic `ModelProvider`. Non-streaming: the framework's
+ * `ModelProvider.invoke` returns a `Promise<ModelCallResult>` and
+ * doesn't expose a streaming seam yet — a streaming adapter is a
+ * separate primitive.
+ */
+export function createAnthropicProvider(options: AnthropicProviderOptions): ModelProvider {
+  const metadata = options.metadata satisfies Omit<ProviderMetadata, 'models'> & {
+    readonly models: readonly AnthropicModelInfo[];
+  };
+  // Build a name → model lookup so invoke can resolve in O(1). Callers
+  // routinely hit the same model for a whole conversation; the map is
+  // built once at construction.
+  const modelsByName = new Map<string, AnthropicModelInfo>(
+    metadata.models.map((m) => [m.name, m] as const),
+  );
+
+  // Cache the SDK client keyed by the currently-resolved API key. When
+  // the resolver returns the same value it did last time, reuse the
+  // client instance (SDK internally maintains a fetch agent and TCP
+  // keepalive — throwing it away on every invoke would tank latency).
+  // When the resolver returns a new value (key rotation), rebuild.
+  let cached: { readonly key: string; readonly client: Anthropic } | undefined;
+  if (options.client !== undefined) {
+    // Dep-injected client — pin to sentinel key so resolveClient below
+    // always returns the same instance regardless of what the resolver
+    // says. Callers using dep injection are opting out of key rotation.
+    cached = { key: '<injected>', client: options.client };
+  }
+
+  async function resolveApiKey(): Promise<string> {
+    if (typeof options.apiKey === 'function') return options.apiKey();
+    return options.apiKey;
+  }
+
+  async function resolveClient(): Promise<Anthropic> {
+    if (options.client !== undefined) return options.client;
+    const key = await resolveApiKey();
+    if (cached !== undefined && cached.key === key) return cached.client;
+    const client = new Anthropic({
+      apiKey: key,
+      ...(options.baseURL !== undefined && { baseURL: options.baseURL }),
+      ...(options.clientOptions ?? {}),
+    });
+    cached = { key, client };
+    return client;
+  }
+
+  return {
+    metadata,
+    async invoke(input: ModelCallInput): Promise<ModelCallResult> {
+      const modelInfo = modelsByName.get(input.model);
+      if (modelInfo === undefined) {
+        throw new Error(
+          `@kindgi/adapter-model-anthropic: provider "${metadata.id}" does not expose model "${input.model}". ` +
+            `Available: ${[...modelsByName.keys()].join(', ') || '<none>'}.`,
+        );
+      }
+      const startedAt = Date.now();
+      const client = await resolveClient();
+
+      const { system, messages } = toAnthropicMessages(input.messages);
+      const tools =
+        input.tools !== undefined && input.tools.length > 0
+          ? toAnthropicTools(input.tools)
+          : undefined;
+
+      const requestOptions: Record<string, unknown> =
+        input.abortSignal !== undefined ? { signal: input.abortSignal } : {};
+      const maxTokens = input.maxOutputTokens ?? modelInfo.maxOutputTokens ?? DEFAULT_MAX_TOKENS;
+
+      const response = await client.messages.create(
+        {
+          model: input.model,
+          max_tokens: maxTokens,
+          ...(system !== undefined && { system }),
+          messages: [...messages],
+          ...(tools !== undefined && { tools: [...tools] }),
+          ...(input.temperature !== undefined && { temperature: input.temperature }),
+        },
+        requestOptions,
+      );
+
+      const durationMs = Date.now() - startedAt;
+      const message = fromAnthropicResponse(response);
+      const usage = toFrameworkUsage(response.usage);
+      const costUsd = computeCostUsd(response.usage, modelInfo.cost);
+
+      return {
+        message,
+        finishReason: mapStopReason(response.stop_reason),
+        usage,
+        costUsd,
+        durationMs,
+        provider: { id: metadata.id, model: input.model },
+      };
+    },
+  };
+}