purra-anthropic 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lybrands
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# purra-anthropic · TypeScript
+
+English | [简体中文](README.zh-CN.md)
+
+Anthropic Messages gateway for PurrA using the official SDK. Supports text,
+function tools, streaming, cancellation, and token usage. Requires Node.js 22+ (ESM).
+
+## Install
+
+Follow [source installation](../../README.md#source-installation), selecting
+`integrations/anthropic/typescript`.
+
+## Configure
+
+Supply the selected model ID and its verified capability snapshot:
+
+```ts
+import { Agent, type ModelCapabilitySnapshot } from "purra";
+import { AnthropicMessagesGateway } from "purra-anthropic";
+
+function createAgent(model: string, capabilities: ModelCapabilitySnapshot) {
+  const gateway = new AnthropicMessagesGateway({
+    model,
+    capabilities,
+    timeoutMs: 60_000,
+  });
+  return new Agent({ model: gateway });
+}
+```
+
+Pass an SDK client through `client` to configure credentials or transport.
+Without one, the gateway creates a client using the SDK's environment configuration.
+
+## Model options
+
+The constructor accepts `thinking`, `outputConfig`, `temperature`, `topP`, and
+`topK`. Choose options supported by the selected model. For example,
+`thinking: { type: "adaptive" }` requires a model that supports adaptive thinking.
+Manual thinking budgets must be integers, at least 1024, and below Core's resolved
+total-generation limit.
+
+## Behavior
+
+SDK retries are disabled; Core controls retry and budget accounting. The gateway
+applies Core's total-generation limit and combines system/developer instructions into the
+system field. Tool choice is automatic when tools are available.
+
+Signed thinking and redacted blocks are retained as private continuation data.
+Keep them with the unchanged assistant message when continuing on the same model;
+they are excluded from public output. Input usage includes cache writes and reads.
+
+Multimodal content, hosted tools, and beta APIs are not supported.
+Other vendors require application adapters.

package/README.zh-CN.md

@@ -0,0 +1,48 @@
+# purra-anthropic · TypeScript
+
+[English](README.md) | 简体中文
+
+使用官方 SDK 将 Anthropic Messages 接入 PurrA，支持文本、函数工具、流式输出、取消和 Token 用量。
+要求 Node.js 22+（ESM）。
+
+## 安装
+
+按照[源码安装说明](../../README.zh-CN.md#从源码安装)操作，选择
+`integrations/anthropic/typescript`。
+
+## 配置
+
+传入所选模型 ID 和已核实的模型能力快照：
+
+```ts
+import { Agent, type ModelCapabilitySnapshot } from "purra";
+import { AnthropicMessagesGateway } from "purra-anthropic";
+
+function createAgent(model: string, capabilities: ModelCapabilitySnapshot) {
+  const gateway = new AnthropicMessagesGateway({
+    model,
+    capabilities,
+    timeoutMs: 60_000,
+  });
+  return new Agent({ model: gateway });
+}
+```
+
+通过 `client` 传入 SDK 客户端，可自定义凭据与传输配置。
+省略时，网关使用 SDK 的环境配置创建客户端。
+
+## 模型参数
+
+构造函数接受 `thinking`、`outputConfig`、`temperature`、`topP` 和 `topK`。
+根据所选模型支持的能力设置参数。例如，`thinking: { type: "adaptive" }`
+要求模型支持自适应 thinking。手动推理预算必须是至少 1024 的整数，且小于 Core 确定的输出上限。
+
+## 行为
+
+SDK 自动重试已关闭，重试与预算核算由 Core 控制。网关使用 Core 确定的输出上限，
+将 system/developer 指令合并到 system 字段，有工具可用时采用自动工具选择。
+
+带签名的 thinking 和 redacted 块保留为私有续接数据。使用同一模型继续对话时，
+应与未改动的 assistant 消息一同保留；它们不会进入公开输出。输入用量包括缓存写入和读取。
+
+不支持多模态内容、服务端托管工具和 beta API。其他厂商由应用提供适配。

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import Anthropic from "@anthropic-ai/sdk";
+import type { MessageCreateParamsNonStreaming } from "@anthropic-ai/sdk/resources/messages";
+import type { ModelCapabilitySnapshot, ModelGateway, ModelRequest, ModelStream, ModelTurn } from "purra";
+export interface AnthropicMessagesOptions {
+    readonly client?: Anthropic;
+    readonly model: string;
+    readonly capabilities: ModelCapabilitySnapshot;
+    readonly timeoutMs?: number;
+    readonly thinking?: MessageCreateParamsNonStreaming["thinking"];
+    readonly outputConfig?: MessageCreateParamsNonStreaming["output_config"];
+    readonly temperature?: number;
+    readonly topP?: number;
+    readonly topK?: number;
+}
+/** Official SDK transport; Core owns execution, retries and cumulative budgets. */
+export declare class AnthropicMessagesGateway implements ModelGateway {
+    #private;
+    readonly capabilities: ModelCapabilitySnapshot;
+    constructor(options: AnthropicMessagesOptions);
+    invoke(request: ModelRequest, signal?: AbortSignal): Promise<ModelTurn>;
+    stream(request: ModelRequest, signal?: AbortSignal): Promise<ModelStream>;
+}

package/dist/index.js

@@ -0,0 +1,251 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { AgentCanceledError, AgentError } from "purra";
+const replayKey = "anthropic_message";
+const maxContinuationChars = 1_000_000;
+function copy(value) { return JSON.parse(JSON.stringify(value)); }
+function text(value) {
+    if (value === null)
+        return "";
+    if (typeof value !== "string")
+        throw new TypeError("Anthropic adapter accepts text messages only");
+    return value;
+}
+function projection(blocks) {
+    let content = "";
+    const toolCalls = [];
+    for (const block of blocks) {
+        if (block.type === "text")
+            content += text(block.text);
+        else if (block.type === "tool_use") {
+            if (!block.input || typeof block.input !== "object" || Array.isArray(block.input))
+                throw new TypeError("Tool input must be an object");
+            toolCalls.push({ id: block.id, name: block.name, arguments: copy(block.input) });
+        }
+        else if (block.type === "thinking") {
+            text(block.thinking);
+            if (typeof block.signature !== "string" || !block.signature)
+                throw new TypeError("Thinking continuation requires a signature");
+        }
+        else if (block.type === "redacted_thinking") {
+            if (typeof block.data !== "string" || !block.data)
+                throw new TypeError("Redacted thinking requires opaque data");
+        }
+        else
+            throw new TypeError("Unsupported Anthropic content block");
+    }
+    return { content, toolCalls };
+}
+function input(messages, model) {
+    const system = [];
+    const rows = [];
+    for (const m of messages) {
+        const content = text(m.content);
+        if (m.toolCalls?.length && m.role !== "assistant")
+            throw new TypeError("Only assistant messages may carry tool calls");
+        if (m.role === "system" || m.role === "developer") {
+            if (content)
+                system.push({ type: "text", text: content });
+            continue;
+        }
+        let blocks;
+        const role = m.role === "assistant" ? "assistant" : "user";
+        if (m.role === "tool") {
+            if (!m.toolCallId)
+                throw new TypeError("Tool output requires a call id");
+            blocks = [{ type: "tool_result", tool_use_id: m.toolCallId, content }];
+        }
+        else if (m.role === "assistant") {
+            const replay = m.providerData?.[replayKey];
+            if (replay != null) {
+                if (typeof replay !== "object" || Array.isArray(replay) || !("model" in replay) || !("content" in replay) || replay.model !== model || !Array.isArray(replay.content))
+                    throw new TypeError("Anthropic continuation belongs to a different model");
+                if (JSON.stringify(replay.content).length > maxContinuationChars)
+                    throw new TypeError("Anthropic continuation exceeds limit");
+                const original = copy(replay.content);
+                const visible = projection(original);
+                if (visible.content !== content || JSON.stringify(visible.toolCalls) !== JSON.stringify(m.toolCalls ?? []))
+                    throw new TypeError("Anthropic continuation does not match assistant message");
+                blocks = original;
+            }
+            else {
+                blocks = content ? [{ type: "text", text: content }] : [];
+                for (const call of m.toolCalls ?? []) {
+                    if (!call.arguments || typeof call.arguments !== "object" || Array.isArray(call.arguments))
+                        throw new TypeError("Tool input must be an object");
+                    blocks.push({ type: "tool_use", id: call.id, name: call.name, input: copy(call.arguments) });
+                }
+            }
+        }
+        else
+            blocks = [{ type: "text", text: content }];
+        if (!blocks.length)
+            throw new TypeError("Anthropic message cannot be empty");
+        const previous = rows.at(-1);
+        if (previous?.role === role)
+            previous.content.push(...blocks);
+        else
+            rows.push({ role, content: blocks });
+    }
+    return { messages: rows, system };
+}
+function attributes(content, model) {
+    if (!content.some(b => b.type === "thinking" || b.type === "redacted_thinking"))
+        return {};
+    if (JSON.stringify(content).length > maxContinuationChars)
+        throw new TypeError("Anthropic continuation exceeds limit");
+    return { [replayKey]: { model, content: copy(content) } };
+}
+function usage(u) {
+    if (u?.input_tokens == null || u.output_tokens == null)
+        return undefined;
+    const cached = u.cache_read_input_tokens ?? 0;
+    const inputs = u.input_tokens + cached + (u.cache_creation_input_tokens ?? 0);
+    return { inputTokens: inputs, generationTokens: u.output_tokens, totalTokens: inputs + u.output_tokens, cachedInputTokens: cached };
+}
+function finish(reason) {
+    if (reason === "end_turn" || reason === "stop_sequence")
+        return "stop";
+    if (reason === "tool_use")
+        return "tool_calls";
+    if (reason === "max_tokens" || reason === "model_context_window_exceeded")
+        return "length";
+    if (reason === "refusal")
+        return "filtered";
+    throw new AgentError("invalid_model_response", "Unsupported Anthropic stop reason");
+}
+function failed(error, signal) {
+    if (signal?.aborted)
+        throw new AgentCanceledError();
+    if (error instanceof Anthropic.APIError)
+        throw new AgentError(error.status === undefined ? "anthropic_transport_error" : `anthropic_http_${error.status}`, "Anthropic request failed");
+    if (error instanceof AgentError)
+        throw error;
+    throw new AgentError("invalid_model_response", "Invalid Anthropic response");
+}
+/** Official SDK transport; Core owns execution, retries and cumulative budgets. */
+export class AnthropicMessagesGateway {
+    capabilities;
+    #client;
+    #options;
+    constructor(options) {
+        if (!options.model.trim())
+            throw new TypeError("Model name is required");
+        if (!Number.isFinite(options.timeoutMs ?? 60000) || (options.timeoutMs ?? 60000) <= 0)
+            throw new TypeError("Timeout must be positive and finite");
+        this.capabilities = options.capabilities;
+        this.#options = { ...options, ...(options.thinking === undefined ? {} : { thinking: copy(options.thinking) }),
+            ...(options.outputConfig === undefined ? {} : { outputConfig: copy(options.outputConfig) }) };
+        this.#client = (options.client ?? new Anthropic()).withOptions({ maxRetries: 0, timeout: options.timeoutMs ?? 60000 });
+    }
+    #request(request) {
+        if (!request.outputBudget)
+            throw new TypeError("Anthropic gateway requires a resolved generation budget");
+        const o = this.#options;
+        if (o.thinking?.type === "enabled" && (!Number.isInteger(o.thinking.budget_tokens) || o.thinking.budget_tokens < 1024 || o.thinking.budget_tokens >= request.outputBudget.maxGenerationTokens))
+            throw new TypeError("Thinking budget must be at least 1024 and below the generation budget");
+        const rows = input(request.messages, o.model);
+        return { model: o.model, messages: rows.messages, max_tokens: request.outputBudget.maxGenerationTokens,
+            ...(rows.system.length ? { system: rows.system } : {}),
+            ...(o.thinking === undefined ? {} : { thinking: o.thinking }),
+            ...(o.outputConfig === undefined ? {} : { output_config: o.outputConfig }),
+            ...(o.temperature === undefined ? {} : { temperature: o.temperature }),
+            ...(o.topP === undefined ? {} : { top_p: o.topP }),
+            ...(o.topK === undefined ? {} : { top_k: o.topK }),
+            ...(request.tools.length ? { tools: request.tools.map(t => {
+                    if (t.inputSchema.type !== "object")
+                        throw new TypeError("Tool schema must describe an object");
+                    return { name: t.name, description: t.description, input_schema: copy(t.inputSchema) };
+                }), tool_choice: { type: "auto" } } : {}),
+        };
+    }
+    async invoke(request, signal) {
+        const params = this.#request(request);
+        if (signal?.aborted)
+            throw new AgentCanceledError();
+        try {
+            const response = await this.#client.messages.create(params, { signal });
+            const tokenUsage = usage(response.usage);
+            return { message: { role: "assistant", ...projection(response.content), providerData: attributes(response.content, params.model) },
+                finishReason: finish(response.stop_reason), appliedGenerationLimit: request.outputBudget.maxGenerationTokens,
+                ...(tokenUsage === undefined ? {} : { usage: tokenUsage }) };
+        }
+        catch (error) {
+            return failed(error, signal);
+        }
+    }
+    async stream(request, signal) {
+        const params = this.#request(request);
+        const client = this.#client;
+        let consumed = false;
+        async function* chunks() {
+            if (consumed)
+                throw new AgentError("invalid_model_response", "Anthropic stream has already been consumed");
+            consumed = true;
+            if (signal?.aborted)
+                throw new AgentCanceledError();
+            let stream;
+            let terminal = false;
+            let privateChars = 0;
+            const emptyTools = new Set();
+            try {
+                stream = client.messages.stream(params, { signal });
+                for await (const event of stream) {
+                    if (event.type === "content_block_start") {
+                        const b = event.content_block;
+                        if (b.type === "tool_use") {
+                            emptyTools.add(event.index);
+                            yield { toolCallDeltas: [{ index: event.index, id: b.id, name: b.name, type: "function" }] };
+                        }
+                        else if (b.type === "text" && b.text)
+                            yield { contentDelta: b.text };
+                        else if (b.type === "thinking" || b.type === "redacted_thinking") {
+                            privateChars += JSON.stringify(b).length;
+                            yield { type: "activity", kind: "working" };
+                        }
+                        else if (b.type !== "text")
+                            throw new TypeError("Unsupported Anthropic content block");
+                    }
+                    else if (event.type === "content_block_delta") {
+                        const d = event.delta;
+                        if (d.type === "text_delta")
+                            yield { contentDelta: d.text };
+                        else if (d.type === "input_json_delta") {
+                            emptyTools.delete(event.index);
+                            yield { toolCallDeltas: [{ index: event.index, argumentsFragment: d.partial_json }] };
+                        }
+                        else if (d.type === "thinking_delta" || d.type === "signature_delta") {
+                            privateChars += d.type === "thinking_delta" ? d.thinking.length : d.signature.length;
+                            yield { type: "activity", kind: "working" };
+                        }
+                        else
+                            throw new TypeError("Unsupported Anthropic content delta");
+                    }
+                    else if (event.type === "content_block_stop" && emptyTools.has(event.index)) {
+                        emptyTools.delete(event.index);
+                        yield { toolCallDeltas: [{ index: event.index, argumentsFragment: "{}" }] };
+                    }
+                    else if (event.type === "message_stop")
+                        terminal = true;
+                    else
+                        yield { type: "activity", kind: "transport" };
+                    if (privateChars > maxContinuationChars)
+                        throw new TypeError("Anthropic continuation exceeds limit");
+                }
+                if (!terminal)
+                    throw new AgentError("upstream_stream_interrupted", "Anthropic stream ended without message_stop");
+                const response = await stream.finalMessage();
+                projection(response.content);
+                const tokenUsage = usage(response.usage);
+                yield { finishReason: finish(response.stop_reason), providerData: attributes(response.content, params.model),
+                    ...(tokenUsage === undefined ? {} : { usage: tokenUsage }) };
+            }
+            catch (error) {
+                failed(error, signal);
+            }
+            finally {
+                stream?.abort();
+            }
+        }
+        return { appliedGenerationLimit: request.outputBudget.maxGenerationTokens, activitySupport: "working", [Symbol.asyncIterator]: chunks };
+    }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "purra-anthropic",
+  "version": "0.5.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Official Anthropic Messages SDK adapter for PurrA",
+  "files": [
+    "dist",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "0.123.0"
+  },
+  "peerDependencies": {
+    "purra": "0.5.0"
+  },
+  "devDependencies": {
+    "purra": "file:../../../typescript",
+    "typescript": "7.0.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.mjs",
+    "check": "npm run build && npm test",
+    "prepack": "npm run build"
+  }
+}