@vincemakes/kiso-provider-anthropic 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kiso contributors
+
+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,9 @@
+# @vincemakes/kiso-provider-anthropic
+
+The Anthropic adapter on the official SDK: wire events mapped to the
+kiso event union, cancellation via the run signal, exhaustive stop-reason
+mapping (refusal/pause_turn/context-window are never completed), real
+usage and cache counters.
+
+Requires Node >= 22. See the repository README for the framework
+overview.

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Anthropic adapter — built on the official SDK, mapping its wire events to
+ * the kiso event union. The kernel never sees Anthropic types (ADR-0001);
+ * everything provider-private (cache_control, thinking deltas) is digested
+ * here.
+ *
+ * Invariants this adapter upholds:
+ * - at least one `usage` precedes the final `stop` (ADR-0003);
+ * - `tool_call_end.input` is the parsed JSON or null — never a partial.
+ *
+ * Tool calls: the SDK streams tool_use as content blocks
+ * (content_block_start with the call id, input_json_delta, then stop).
+ * The id in the start block IS the callId the kernel echoes back.
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import type { Adapter } from "@vincemakes/kiso-core";
+/** Config accepted by the high-level factory (七: the provider owns its SDK). */
+export interface AnthropicProviderConfig {
+    readonly apiKey?: string;
+    readonly baseUrl?: string;
+}
+/**
+ * High-level factory (七): builds the adapter FROM CONFIG, owning the SDK
+ * inside this package. Consumers (and the runtime's lazy provider path)
+ * import ONLY @vincemakes/kiso-provider-anthropic — the SDK stays a private
+ * dependency of this package, so nested installs resolve it next to here,
+ * never through a hoisted root.
+ */
+export declare function createAnthropicProvider(config?: AnthropicProviderConfig): Adapter;
+export declare function createAnthropicAdapter(client: Anthropic): Adapter;

package/dist/index.js

@@ -0,0 +1,289 @@
+/**
+ * Anthropic adapter — built on the official SDK, mapping its wire events to
+ * the kiso event union. The kernel never sees Anthropic types (ADR-0001);
+ * everything provider-private (cache_control, thinking deltas) is digested
+ * here.
+ *
+ * Invariants this adapter upholds:
+ * - at least one `usage` precedes the final `stop` (ADR-0003);
+ * - `tool_call_end.input` is the parsed JSON or null — never a partial.
+ *
+ * Tool calls: the SDK streams tool_use as content blocks
+ * (content_block_start with the call id, input_json_delta, then stop).
+ * The id in the start block IS the callId the kernel echoes back.
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import { mapApiError } from "@vincemakes/kiso-core";
+/**
+ * High-level factory (七): builds the adapter FROM CONFIG, owning the SDK
+ * inside this package. Consumers (and the runtime's lazy provider path)
+ * import ONLY @vincemakes/kiso-provider-anthropic — the SDK stays a private
+ * dependency of this package, so nested installs resolve it next to here,
+ * never through a hoisted root.
+ */
+export function createAnthropicProvider(config = {}) {
+    const client = new Anthropic({
+        ...(config.apiKey !== undefined ? { apiKey: config.apiKey } : {}),
+        ...(config.baseUrl !== undefined ? { baseURL: config.baseUrl } : {}),
+    });
+    return createAnthropicAdapter(client);
+}
+export function createAnthropicAdapter(client) {
+    return {
+        async *stream(options) {
+            // D4: the stream CREATION is inside the error normalization —
+            // connection/timeout/5xx failures before the first byte are
+            // mapped, retryable StructuredErrors.
+            let stream;
+            try {
+                stream = client.messages.stream({
+                    model: options.model,
+                    ...(options.systemPrompt !== undefined ? { system: options.systemPrompt } : {}),
+                    max_tokens: options.maxTokens ?? 4096,
+                    messages: toAnthropicMessages(options.messages),
+                    ...(options.tools?.length ? { tools: toAnthropicTools(options.tools) } : {}),
+                    ...(options.temperature !== undefined ? { temperature: options.temperature } : {}),
+                }, 
+                // Phase B: cancellation reaches the SDK, which aborts the fetch.
+                options.signal !== undefined ? { signal: options.signal } : undefined);
+            }
+            catch (err) {
+                throw toAnthropicError(err);
+            }
+            let inputTokens = null;
+            let outputTokens = null;
+            let cacheRead = null;
+            let cacheWrite = null;
+            // 九: "usage SEEN" (data arrived) is distinct from "usage YIELDED"
+            // (an event left the adapter). message_start may report usage with
+            // no message_delta ever following — the stop must then still be
+            // preceded by an honest usage event built from that data.
+            let usageSeen = false;
+            let usageYielded = false;
+            let stopReasonSeen = false;
+            let stopReason = "end_turn";
+            const toolBuffer = new Map();
+            try {
+                for await (const event of stream) {
+                    switch (event.type) {
+                        case "message_start":
+                            inputTokens = event.message.usage.input_tokens ?? null;
+                            // D5: cache counters are READ from the SDK — never
+                            // faked as zero.
+                            cacheRead = event.message.usage.cache_read_input_tokens ?? null;
+                            cacheWrite = event.message.usage.cache_creation_input_tokens ?? null;
+                            if (event.message.usage.input_tokens !== undefined)
+                                usageSeen = true;
+                            break;
+                        case "content_block_start": {
+                            const block = event.content_block;
+                            if (block.type === "text") {
+                                yield { seq: 0, type: "text_start" };
+                            }
+                            else if (block.type === "tool_use") {
+                                toolBuffer.set(event.index, { id: block.id, name: block.name, json: "" });
+                                yield {
+                                    seq: 0,
+                                    type: "tool_call_start",
+                                    callId: block.id,
+                                    name: block.name,
+                                };
+                            }
+                            break;
+                        }
+                        case "content_block_delta": {
+                            const delta = event.delta;
+                            if (delta.type === "text_delta") {
+                                yield { seq: 0, type: "text_delta", text: delta.text };
+                            }
+                            else if (delta.type === "input_json_delta") {
+                                const buffered = toolBuffer.get(event.index);
+                                if (buffered) {
+                                    buffered.json += delta.partial_json;
+                                    yield {
+                                        seq: 0,
+                                        type: "tool_call_input_delta",
+                                        callId: buffered.id,
+                                        inputJsonDelta: delta.partial_json,
+                                    };
+                                }
+                            }
+                            else if (delta.type === "thinking_delta") {
+                                yield { seq: 0, type: "thinking", text: delta.thinking };
+                            }
+                            break;
+                        }
+                        case "content_block_stop": {
+                            const buffered = toolBuffer.get(event.index);
+                            if (buffered) {
+                                toolBuffer.delete(event.index);
+                                let input = null;
+                                try {
+                                    input = JSON.parse(buffered.json || "{}");
+                                }
+                                catch {
+                                    input = null; // never a silent repair
+                                }
+                                yield {
+                                    seq: 0,
+                                    type: "tool_call_end",
+                                    callId: buffered.id,
+                                    name: buffered.name,
+                                    input,
+                                };
+                            }
+                            // Text blocks end implicitly: the next TextStart (or
+                            // the terminal) closes the previous block (ADR-0003).
+                            break;
+                        }
+                        case "message_delta":
+                            stopReasonSeen = true;
+                            stopReason = mapStopReason((event.delta.stop_reason ?? "error"));
+                            outputTokens = event.usage?.output_tokens ?? null;
+                            if (event.usage?.output_tokens !== undefined)
+                                usageSeen = true;
+                            usageYielded = true;
+                            yield {
+                                seq: 0,
+                                type: "usage",
+                                inputTokens,
+                                outputTokens,
+                                cacheRead,
+                                cacheWrite,
+                                known: usageSeen,
+                            };
+                            break;
+                        case "message_stop":
+                            // 六/九: EVERY stop path emits a usage first. If no
+                            // message_delta yielded one, but message_start DID
+                            // report usage data, an honest KNOWN usage is built
+                            // from that data now — only a truly silent provider
+                            // gets known:false (nulls, never faked). The
+                            // ADR-0003 invariant "usage precedes stop" holds
+                            // structurally.
+                            if (!usageYielded) {
+                                yield {
+                                    seq: 0,
+                                    type: "usage",
+                                    inputTokens,
+                                    outputTokens,
+                                    cacheRead,
+                                    cacheWrite,
+                                    known: usageSeen,
+                                };
+                            }
+                            // D3: a message_stop with NO delta means the
+                            // provider never reported a stop reason — that is
+                            // an error, never a default end_turn.
+                            yield { seq: 0, type: "stop", reason: stopReasonSeen ? stopReason : "error" };
+                            break;
+                    }
+                }
+            }
+            catch (err) {
+                throw toAnthropicError(err);
+            }
+        },
+    };
+}
+// ── Mapping helpers ────────────────────────────────────────────────────
+/**
+ * Exhaustive over the SDK's CLOSED StopReason union (Area 6): a new SDK
+ * enum is a compile error here, and none of them degrades into `end_turn`.
+ * `pause_turn` and `refusal` are explicit non-completions.
+ */
+function mapStopReason(reason) {
+    switch (reason) {
+        case "end_turn":
+            return "end_turn";
+        case "max_tokens":
+            return "max_tokens";
+        case "stop_sequence":
+            return "stop_sequence";
+        case "tool_use":
+            return "tool_use";
+        case "pause_turn":
+            return "pause_turn";
+        case "refusal":
+            return "refusal";
+        case "model_context_window_exceeded":
+            return "context_window";
+        default: {
+            // The `never` annotation fails the typecheck when the SDK grows
+            // a new member; at runtime an unexpected value is an honest
+            // `error`, never a completed.
+            const _exhaustive = reason;
+            void _exhaustive;
+            return "error";
+        }
+    }
+}
+function toAnthropicContent(content) {
+    if (typeof content === "string") {
+        return [{ type: "text", text: content }];
+    }
+    return content.map((block) => {
+        if (block.type === "text")
+            return { type: "text", text: block.text };
+        return {
+            type: "image",
+            source: block.sourceType === "url"
+                ? { type: "url", url: block.url ?? "" }
+                : { type: "base64", media_type: block.mediaType ?? "image/png", data: block.data ?? "" },
+        };
+    });
+}
+function toAnthropicMessages(messages) {
+    const out = [];
+    for (const msg of messages) {
+        if (msg.role === "user") {
+            out.push({ role: "user", content: toAnthropicContent(msg.content) });
+        }
+        else if (msg.role === "assistant") {
+            out.push({
+                role: "assistant",
+                content: msg.blocks.map(toAnthropicBlock),
+            });
+        }
+        else {
+            // tool result: Anthropic nests them as a user message.
+            out.push({
+                role: "user",
+                content: [
+                    {
+                        type: "tool_result",
+                        tool_use_id: msg.callId,
+                        content: toAnthropicContent(msg.content),
+                        is_error: msg.isError,
+                    },
+                ],
+            });
+        }
+    }
+    return out;
+}
+function toAnthropicBlock(block) {
+    return block.type === "text"
+        ? { type: "text", text: block.text }
+        : { type: "tool_use", id: block.callId, name: block.name, input: block.input };
+}
+function toAnthropicTools(tools) {
+    return tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        input_schema: t.inputSchema,
+    }));
+}
+function toAnthropicError(err) {
+    // D4: connection-level failures are recognized, not lumped into unknown.
+    if (err instanceof Anthropic.APIConnectionTimeoutError) {
+        return { code: "timeout", retryable: true, message: err.message };
+    }
+    if (err instanceof Anthropic.APIConnectionError) {
+        return { code: "network", retryable: true, message: err.message };
+    }
+    if (err instanceof Anthropic.APIError) {
+        return mapApiError(err.status, err.message);
+    }
+    return err;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@vincemakes/kiso-provider-anthropic",
+  "version": "0.1.0",
+  "description": "kiso Anthropic adapter \u2014 official SDK wire events mapped to the kiso event union.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.115.0",
+    "@vincemakes/kiso-core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vincemakes/kiso.git",
+    "directory": "packages/provider-anthropic"
+  },
+  "bugs": {
+    "url": "https://github.com/vincemakes/kiso/issues"
+  },
+  "homepage": "https://github.com/vincemakes/kiso/tree/main/packages/provider-anthropic#readme"
+}