@galdor/provider-anthropic 0.3.0

package/src/errors.ts

@@ -0,0 +1,121 @@
+/**
+ * Normalization of Anthropic HTTP failures into galdor's typed error surface.
+ *
+ * The Messages API signals failure both through the HTTP status code and through
+ * a JSON `error.type` discriminator in the body. This module folds the two into
+ * a single {@link ErrorKind}, preferring the body's classification when present
+ * and falling back to the status code otherwise, then wraps the result in an
+ * {@link APIError} so callers can branch on `instanceof` of the concrete error
+ * subclasses produced by {@link classify}.
+ */
+
+import { APIError, classify, type ErrorKind, parseRetryAfter } from "@galdor/core/provider";
+
+const PROVIDER_NAME = "anthropic";
+
+/** Shape of the JSON error envelope returned by the Anthropic Messages API. */
+interface AnthropicErrorBody {
+  type?: string;
+  error?: { type?: string; message?: string };
+}
+
+/** Map an HTTP status code to a galdor {@link ErrorKind} as a coarse fallback. */
+function kindForStatus(code: number): ErrorKind {
+  if (code === 401 || code === 403) return "auth";
+  if (code === 429) return "rate_limited";
+  if (code >= 500) return "server";
+  if (code >= 400) return "invalid_request";
+  return "server";
+}
+
+/**
+ * Map Anthropic's `error.type` discriminator to a galdor {@link ErrorKind}.
+ *
+ * @returns The matching kind, or `undefined` when the type is unknown so the
+ * caller can fall back to {@link kindForStatus}.
+ */
+function kindForType(t: string | undefined): ErrorKind | undefined {
+  switch (t) {
+    case "authentication_error":
+    case "permission_error":
+      return "auth";
+    case "rate_limit_error":
+    case "overloaded_error":
+      return "rate_limited";
+    case "invalid_request_error":
+    case "not_found_error":
+      return "invalid_request";
+    case "api_error":
+      return "server";
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Minimal structural view of a fetch `Response` needed to classify a failure.
+ *
+ * Accepting this narrow interface (rather than the full `Response`) keeps
+ * {@link normalizeHTTPError} testable with lightweight stubs.
+ */
+export interface ResponseLike {
+  /** HTTP status code of the failed response. */
+  status: number;
+  /** Header accessor; used to read `retry-after`. */
+  headers: { get(name: string): string | null };
+  /** Reads the full response body as text. */
+  text(): Promise<string>;
+}
+
+/**
+ * Convert a non-2xx Anthropic response into a typed galdor {@link APIError}.
+ *
+ * The body is read once and parsed as JSON; when it carries an `error.type`,
+ * that classification wins over the status-derived kind, and the human-readable
+ * `error.message` becomes the error message. A `retry-after` header, if present,
+ * is parsed and attached. The result is passed through {@link classify} so the
+ * caller receives the concrete error subclass for the kind.
+ *
+ * @param res - The failed response (or a structural stand-in).
+ * @returns A classified {@link APIError} describing the failure.
+ * @example
+ * if (Math.floor(res.status / 100) !== 2) throw await normalizeHTTPError(res);
+ */
+export async function normalizeHTTPError(res: ResponseLike): Promise<APIError> {
+  const text = await res.text().catch(() => "");
+  let kind = kindForStatus(res.status);
+  let message = `anthropic: HTTP ${res.status}`;
+  if (text) {
+    try {
+      const body = JSON.parse(text) as AnthropicErrorBody;
+      if (body.error?.message) message = body.error.message;
+      const k = kindForType(body.error?.type);
+      if (k) kind = k;
+    } catch {
+      /* non-JSON body: keep the status-derived kind and default message */
+    }
+  }
+  const retryAfter = parseRetryAfter(res.headers.get("retry-after") ?? "", new Date());
+  return classify(
+    new APIError({ kind, provider: PROVIDER_NAME, statusCode: res.status, message, ...(retryAfter !== null ? { retryAfter } : {}) }),
+  );
+}
+
+/**
+ * Build a typed galdor {@link APIError} from an Anthropic streaming `error`
+ * frame, which carries no HTTP status.
+ *
+ * The mid-stream `error` SSE event reports its `error.type` discriminator and a
+ * human message but, unlike an HTTP failure, has no status code to fall back on.
+ * The type is mapped through the same {@link kindForType} table used for HTTP
+ * errors and defaults to `server` when unrecognized. The result is passed
+ * through {@link classify} so the caller receives the concrete subclass.
+ *
+ * @param type - The `error.type` discriminator from the frame, if any.
+ * @param message - The human-readable error message from the frame.
+ * @returns A classified {@link APIError} with `statusCode` 0.
+ */
+export function classifyStreamError(type: string | undefined, message: string): APIError {
+  const kind = kindForType(type) ?? "server";
+  return classify(new APIError({ kind, provider: PROVIDER_NAME, statusCode: 0, message }));
+}

package/src/index.ts

@@ -0,0 +1,179 @@
+/**
+ * `@galdor/provider-anthropic` — Anthropic (Claude Messages API) adapter.
+ *
+ * Implements the galdor {@link Provider} interface over the `/v1/messages`
+ * endpoint, supporting tool use, vision input, extended thinking, prompt
+ * caching, and structured output (expressed as a forced single tool call). Both
+ * a buffered {@link AnthropicProvider.generate} and an incremental
+ * {@link AnthropicProvider.stream} path are provided; construct an instance with
+ * {@link newAnthropic}.
+ */
+
+import {
+  APIError,
+  type Capabilities,
+  classify,
+  type Event,
+  fetchWithHeaderTimeout,
+  type Provider,
+  type Request,
+  type Response,
+  type RunContext,
+  validateRequest,
+} from "@galdor/core/provider";
+import { buildRequest, extractStructuredOutput, type MessageResponse, responseFromWire } from "./convert.ts";
+import { normalizeHTTPError } from "./errors.ts";
+import { streamMessages } from "./stream.ts";
+
+const PROVIDER_NAME = "anthropic";
+const DEFAULT_BASE_URL = "https://api.anthropic.com";
+const DEFAULT_API_VERSION = "2023-06-01";
+
+/** Construction options for an {@link AnthropicProvider}. */
+export interface Config {
+  /** Anthropic API key; required and must be non-empty. */
+  apiKey: string;
+  /** Overrides the API endpoint. Defaults to `https://api.anthropic.com`; trailing slashes are trimmed. */
+  baseURL?: string;
+  /** Value sent as the `anthropic-version` header. Defaults to `2023-06-01`. */
+  apiVersion?: string;
+  /** Suffix appended to the default user-agent when non-empty. */
+  userAgent?: string;
+  /**
+   * Response-header timeout in milliseconds: abort if the server doesn't return
+   * headers in time. Streaming bodies are NOT cut off once headers arrive.
+   * Defaults to 60000 (60 s); `0` disables it. Also settable via
+   * `LLM_HTTP_TIMEOUT` through providerset.
+   */
+  timeoutMs?: number;
+}
+
+/**
+ * galdor {@link Provider} backed by the Anthropic Messages API.
+ *
+ * Holds connection settings and builds the per-request headers; the actual wire
+ * translation and SSE handling live in the conversion and streaming helpers.
+ * Prefer {@link newAnthropic} to construct one.
+ */
+export class AnthropicProvider implements Provider {
+  readonly #apiKey: string;
+  readonly #baseURL: string;
+  readonly #apiVersion: string;
+  readonly #userAgent: string;
+  readonly #timeoutMs: number;
+
+  /**
+   * Create a provider from the given {@link Config}.
+   *
+   * @throws {Error} When `apiKey` is missing or blank.
+   */
+  constructor(cfg: Config) {
+    if (!cfg.apiKey || cfg.apiKey.trim() === "") throw new Error("anthropic: apiKey is required");
+    this.#apiKey = cfg.apiKey;
+    this.#baseURL = (cfg.baseURL || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.#apiVersion = cfg.apiVersion || DEFAULT_API_VERSION;
+    this.#userAgent = cfg.userAgent ?? "";
+    this.#timeoutMs = cfg.timeoutMs ?? 60_000;
+  }
+
+  /** @returns The provider's stable identifier, `"anthropic"`. */
+  name(): string {
+    return PROVIDER_NAME;
+  }
+
+  /** @returns The feature set this adapter supports, including the model context window. */
+  capabilities(): Capabilities {
+    return {
+      streaming: true,
+      toolCalling: true,
+      structuredOutput: true,
+      promptCaching: true,
+      visionInput: true,
+      reasoning: true,
+      maxContextTokens: 200_000,
+    };
+  }
+
+  /** Build the request headers, folding in any configured user-agent suffix. */
+  #headers(): Record<string, string> {
+    let ua = "galdor-anthropic/0.1";
+    if (this.#userAgent) ua += ` ${this.#userAgent}`;
+    return {
+      "x-api-key": this.#apiKey,
+      "anthropic-version": this.#apiVersion,
+      "content-type": "application/json",
+      "user-agent": ua,
+    };
+  }
+
+  /**
+   * Run a single buffered completion against `/v1/messages`.
+   *
+   * Lowers the request to the wire shape, POSTs it, decodes the full response,
+   * and applies structured-output extraction when a `json_schema` format was
+   * requested.
+   *
+   * @param req - The galdor request to run.
+   * @param ctx - Optional run context; its abort signal cancels the request.
+   * @returns The completed galdor {@link Response}.
+   * @throws {APIError} On a non-2xx status or when the response body cannot be decoded.
+   */
+  async generate(req: Request, ctx?: RunContext): Promise<Response> {
+    const capErr = validateRequest(this.capabilities(), req);
+    if (capErr) throw capErr;
+    const wire = buildRequest(req, false);
+    const res = await fetchWithHeaderTimeout(
+      `${this.#baseURL}/v1/messages`,
+      { method: "POST", headers: this.#headers(), body: JSON.stringify(wire) },
+      this.#timeoutMs,
+      ctx?.signal,
+    );
+    if (Math.floor(res.status / 100) !== 2) throw await normalizeHTTPError(res);
+
+    const rawBytes = new Uint8Array(await res.arrayBuffer());
+    let body: MessageResponse;
+    try {
+      body = JSON.parse(new TextDecoder().decode(rawBytes)) as MessageResponse;
+    } catch (e) {
+      throw classify(
+        new APIError({ kind: "server", provider: PROVIDER_NAME, statusCode: res.status, message: `decode response: ${(e as Error).message}` }),
+      );
+    }
+    let out = responseFromWire(body, rawBytes);
+    if (req.responseFormat?.type === "json_schema") out = extractStructuredOutput(out, req.responseFormat.name);
+    return out;
+  }
+
+  /**
+   * Run a streaming completion, yielding incremental provider events.
+   *
+   * @param req - The galdor request to run.
+   * @param ctx - Optional run context; its abort signal cancels the stream.
+   * @returns An async iterable of {@link Event}s ending with a message-stop event.
+   */
+  stream(req: Request, ctx?: RunContext): AsyncIterable<Event> {
+    const capErr = validateRequest(this.capabilities(), req);
+    if (capErr) throw capErr;
+    const wire = buildRequest(req, true);
+    return streamMessages(`${this.#baseURL}/v1/messages`, this.#headers(), wire, ctx?.signal, this.#timeoutMs);
+  }
+}
+
+/**
+ * Construct an {@link AnthropicProvider} from a {@link Config}.
+ *
+ * @param cfg - Connection options; `apiKey` is required.
+ * @returns A ready-to-use provider instance.
+ * @throws {Error} When `apiKey` is missing or blank.
+ * @example
+ * const provider = newAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });
+ * const resp = await provider.generate({
+ *   model: "claude-haiku-4-5",
+ *   messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+ * });
+ */
+export function newAnthropic(cfg: Config): AnthropicProvider {
+  return new AnthropicProvider(cfg);
+}
+
+export { normalizeHTTPError } from "./errors.ts";

package/src/stream.ts

@@ -0,0 +1,263 @@
+/**
+ * Anthropic streaming over Server-Sent Events.
+ *
+ * Translates Anthropic's SSE event sequence (`message_start`, `content_block_*`,
+ * `message_delta`, `message_stop`) into galdor's provider {@link Event} stream
+ * ({@link EventType.MessageStart}, {@link EventType.ContentDelta},
+ * {@link EventType.ToolCallDelta}, {@link EventType.MessageStop}). The bytes
+ * arrive in arbitrary chunks, so the reader buffers and splits on the blank-line
+ * delimiter that separates SSE messages. Consume the result with `for await`, or
+ * fold it back into a single Response with `collectStream`.
+ */
+
+import { type Event, EventType, fetchWithHeaderTimeout } from "@galdor/core/provider";
+import { ContentType, type Message, Role, type StopReason, type Usage } from "@galdor/core/schema";
+import { classifyStreamError, normalizeHTTPError } from "./errors.ts";
+import type { MessageRequest } from "./convert.ts";
+
+/**
+ * Token-count fields shared by the `message_start` and `message_delta` usage
+ * objects. Cache counts are reported only when prompt caching is in play, so
+ * every field is optional.
+ */
+interface WireUsage {
+  input_tokens?: number;
+  output_tokens?: number;
+  cache_creation_input_tokens?: number;
+  cache_read_input_tokens?: number;
+}
+
+/**
+ * Decoded payload of a single SSE `data:` line. Fields are populated selectively
+ * depending on `type`; the inline comments note which event each group belongs to.
+ */
+interface SSEEvent {
+  type: string;
+  // message_start
+  message?: { model?: string; usage?: WireUsage };
+  // content_block_start
+  index?: number;
+  content_block?: { type?: string; id?: string; name?: string };
+  // content_block_delta
+  delta?: { type?: string; text?: string; partial_json?: string; stop_reason?: string; thinking?: string; signature?: string };
+  // message_delta
+  usage?: WireUsage;
+  // error
+  error?: { type?: string; message?: string };
+}
+
+/** A zero-valued usage accumulator to fill in as the stream reports token counts. */
+function emptyUsage(): Usage {
+  return { inputTokens: 0, outputTokens: 0, cacheCreationTokens: 0, cacheReadTokens: 0 };
+}
+
+/**
+ * Fold any cache token counts from a wire usage object into the running usage,
+ * so streamed usage matches the non-streaming path. Counts are reported only
+ * when present, so each is applied only when non-zero.
+ */
+function foldCacheUsage(usage: Usage, wire: WireUsage | undefined): void {
+  if (wire?.cache_creation_input_tokens) usage.cacheCreationTokens = wire.cache_creation_input_tokens;
+  if (wire?.cache_read_input_tokens) usage.cacheReadTokens = wire.cache_read_input_tokens;
+}
+
+/**
+ * Mutable accumulator for extended-thinking deltas. Thinking and signature
+ * fragments are gathered here across the stream rather than forwarded as live
+ * events, then attached to the terminal MessageStop as a single thinking part.
+ */
+interface Reasoning {
+  thinking: string;
+  signature: string;
+}
+
+/**
+ * Build the terminal assistant {@link Message} carrying any accumulated
+ * reasoning, or `undefined` when none was streamed. The assistant text rides the
+ * content deltas, so this message holds only the thinking part; downstream
+ * `collectStream` harvests the thinking block from here.
+ */
+function reasoningMessage(r: Reasoning): Message | undefined {
+  if (r.thinking === "" && r.signature === "") return undefined;
+  return {
+    role: Role.Assistant,
+    content: [{ type: ContentType.Thinking, text: r.thinking, signature: r.signature }],
+  };
+}
+
+/**
+ * Map a raw Anthropic stop-reason string to a {@link StopReason}. Known reasons
+ * map to themselves; empty and unknown values pass through unchanged (matching
+ * the non-streaming path) rather than being coerced to `end_turn`.
+ */
+function normalizeStopReason(s: string | undefined): StopReason {
+  switch (s) {
+    case "end_turn":
+    case "max_tokens":
+    case "tool_use":
+    case "stop_sequence":
+    case "refusal":
+      return s;
+    default:
+      return (s ?? "") as StopReason;
+  }
+}
+
+/**
+ * POST a streaming `/v1/messages` request and yield galdor provider events.
+ *
+ * Sends the request with `stream: true` already set on `body`, then reads the
+ * SSE response incrementally: each complete event block is parsed and converted
+ * into zero or more {@link Event}s. Running token usage, the model name, and the
+ * stop reason are accumulated across the stream and emitted as a final
+ * {@link EventType.MessageStop} once the body is exhausted.
+ *
+ * @param url - Full messages endpoint to POST to.
+ * @param headers - Request headers, including auth and content type.
+ * @param body - The wire request; its `stream` flag should already be true.
+ * @param signal - Optional abort signal to cancel the in-flight request.
+ * @returns An async generator of provider events, ending with a MessageStop.
+ * @throws {APIError} When the response status is not 2xx (see {@link normalizeHTTPError}).
+ * @throws {Error} When a 2xx response unexpectedly carries no body.
+ * @example
+ * for await (const ev of streamMessages(url, headers, wire, signal)) {
+ *   if (ev.type === EventType.ContentDelta) process.stdout.write(ev.contentDelta);
+ * }
+ */
+export async function* streamMessages(
+  url: string,
+  headers: Record<string, string>,
+  body: MessageRequest,
+  signal: AbortSignal | undefined,
+  timeoutMs = 0,
+): AsyncGenerator<Event> {
+  const res = await fetchWithHeaderTimeout(
+    url,
+    { method: "POST", headers: { ...headers, accept: "text/event-stream" }, body: JSON.stringify(body) },
+    timeoutMs,
+    signal,
+  );
+  if (Math.floor(res.status / 100) !== 2) throw await normalizeHTTPError(res);
+  if (!res.body) throw new Error("anthropic: streaming response had no body");
+
+  // Maps a content-block index to its tool-call id so later input_json_delta
+  // events (which carry only the index) can be attributed to the right call.
+  const toolIndex = new Map<number, string>();
+  const usage = emptyUsage();
+  const reasoning: Reasoning = { thinking: "", signature: "" };
+  let model = "";
+  // Empty until a message_delta reports one; passed through as-is, matching the
+  // oracle (a stream that ends without a stop_reason emits an empty reason).
+  let stopReason = "" as StopReason;
+
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  for await (const chunk of res.body as unknown as AsyncIterable<Uint8Array>) {
+    buffer += decoder.decode(chunk, { stream: true });
+    // SSE messages are separated by a blank line.
+    let sep: number;
+    while ((sep = buffer.indexOf("\n\n")) !== -1) {
+      const rawEvent = buffer.slice(0, sep);
+      buffer = buffer.slice(sep + 2);
+      const data = parseDataLine(rawEvent);
+      if (data === undefined) continue;
+      // handleEvent throws on a mid-stream `error` frame; the throw propagates
+      // through `yield*` to the `for await` consumer.
+      yield* handleEvent(data, { toolIndex, usage, reasoning }, (m) => (model = m), (sr) => (stopReason = sr));
+    }
+  }
+
+  const message = reasoningMessage(reasoning);
+  yield { type: EventType.MessageStop, stopReason, usage, model, ...(message ? { message } : {}) };
+}
+
+/**
+ * Extract and JSON-parse the `data:` payload from one SSE event block.
+ *
+ * Concatenates multiple `data:` lines within the block, ignores the terminal
+ * `[DONE]` sentinel and empty payloads, and swallows parse failures.
+ *
+ * @returns The decoded event, or `undefined` when there is nothing to emit.
+ */
+function parseDataLine(rawEvent: string): SSEEvent | undefined {
+  const dataParts: string[] = [];
+  for (const line of rawEvent.split("\n")) {
+    if (line.startsWith("data:")) dataParts.push(line.slice(5).trimStart());
+  }
+  if (dataParts.length === 0) return undefined;
+  const payload = dataParts.join("\n");
+  if (payload === "" || payload === "[DONE]") return undefined;
+  try {
+    return JSON.parse(payload) as SSEEvent;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Convert one decoded SSE event into galdor provider events, mutating the shared
+ * accumulator state (tool-index map, usage, and reasoning) and reporting the
+ * model and stop reason through the supplied setters. Block-stop, message-stop
+ * and ping events produce nothing mid-stream. Thinking and signature deltas are
+ * accumulated silently rather than forwarded. An `error` frame throws.
+ *
+ * @throws {APIError} When the frame is a mid-stream `error` event.
+ */
+function* handleEvent(
+  ev: SSEEvent,
+  state: { toolIndex: Map<number, string>; usage: Usage; reasoning: Reasoning },
+  setModel: (m: string) => void,
+  setStop: (sr: StopReason) => void,
+): Generator<Event> {
+  switch (ev.type) {
+    case "message_start": {
+      const model = ev.message?.model ?? "";
+      if (model) setModel(model);
+      if (ev.message?.usage?.input_tokens) state.usage.inputTokens = ev.message.usage.input_tokens;
+      foldCacheUsage(state.usage, ev.message?.usage);
+      yield { type: EventType.MessageStart, model, usage: { ...state.usage } };
+      break;
+    }
+    case "content_block_start": {
+      const cb = ev.content_block;
+      if (cb?.type === "tool_use" && typeof ev.index === "number") {
+        const id = cb.id ?? "";
+        state.toolIndex.set(ev.index, id);
+        yield { type: EventType.ToolCallDelta, toolCallDelta: { id, name: cb.name ?? "", argumentsDelta: "" } };
+      }
+      break;
+    }
+    case "content_block_delta": {
+      const d = ev.delta;
+      if (d?.type === "text_delta" && d.text) {
+        yield { type: EventType.ContentDelta, contentDelta: d.text };
+      } else if (d?.type === "input_json_delta" && typeof ev.index === "number") {
+        const id = state.toolIndex.get(ev.index) ?? "";
+        yield { type: EventType.ToolCallDelta, toolCallDelta: { id, name: "", argumentsDelta: d.partial_json ?? "" } };
+      } else if (d?.type === "thinking_delta" && d.thinking) {
+        // Extended-thinking text; gather it for the terminal message, not live.
+        state.reasoning.thinking += d.thinking;
+      } else if (d?.type === "signature_delta" && d.signature) {
+        // The provider-issued signature for the thinking block, gathered silently.
+        state.reasoning.signature += d.signature;
+      }
+      break;
+    }
+    case "message_delta": {
+      if (ev.delta?.stop_reason) setStop(normalizeStopReason(ev.delta.stop_reason));
+      if (ev.usage?.output_tokens) state.usage.outputTokens = ev.usage.output_tokens;
+      // Anthropic can also report input_tokens here (not just at message_start);
+      // track the latest so the terminal event carries them, matching the oracle.
+      if (ev.usage?.input_tokens) state.usage.inputTokens = ev.usage.input_tokens;
+      foldCacheUsage(state.usage, ev.usage);
+      break;
+    }
+    case "error": {
+      // A mid-stream failure: classify by error type and propagate by throwing,
+      // which surfaces to the `for await` consumer rather than being swallowed.
+      throw classifyStreamError(ev.error?.type, ev.error?.message ?? "anthropic: stream error");
+    }
+    // content_block_stop / message_stop / ping: nothing to emit mid-stream.
+  }
+}