@visual-z/xeno 0.1.0

package/src/runtime/provider.ts

@@ -0,0 +1,498 @@
+/**
+ * The Anthropic adapter, and the interface every adapter implements.
+ *
+ * Everything the core produces is provider-neutral by construction, so the
+ * mapping lives here and nowhere else.
+ *
+ * `Provider` is an interface rather than a base class on purpose. Two adapters
+ * share a contract, not an implementation -- there is nothing for a base class
+ * to hold. Worse, a base class that constructs an Anthropic client drags the
+ * SDK into every subclass, including test fakes that never make a request,
+ * which is how an SDK dependency ends up in code that has nothing to do with
+ * Anthropic.
+ *
+ * Three rules this file exists to honour, all of which would otherwise be
+ * discovered as production failures:
+ *
+ *   THINKING BLOCKS REPLAY VERBATIM. The API rejects blocks whose content was
+ *   modified, and a block whose text is empty still has to go back unchanged.
+ *   The core therefore carries the raw block opaquely and this file passes it
+ *   straight through -- it never reconstructs one from text.
+ *
+ *   THE FROZEN PREFIX CARRIES THE CACHE BREAKPOINT. System and tools render at
+ *   the front of the prompt, so one explicit breakpoint on the system block
+ *   gives the expensive shared part a read point that survives whatever
+ *   happens later in messages. Top-level auto-caching then handles the growing
+ *   tail.
+ *
+ *   EVERY RESPONSE IS MEASURED. Usage comes back on each call and is returned
+ *   alongside the message, because a cache that silently stopped working costs
+ *   money without ever raising an error.
+ */
+
+import Anthropic from "@anthropic-ai/sdk";
+import type { Message, ContentBlock, FrozenPrefix } from "../core/project.ts";
+import type { AssistantBlock } from "../core/events.ts";
+import { assertNever } from "../core/exhaustive.ts";
+import type { UsageSample } from "./usage.ts";
+import { type Effort, type ModelSpec, CLAUDE_OPUS_5 } from "./model.ts";
+import { withRetry, DEFAULT_RETRY, type RetryPolicy } from "./retry.ts";
+import { anthropicOAuthHeaders } from "./oauth.ts";
+
+export interface ToolSchema {
+  name: string;
+  description: string;
+  input_schema: {
+    type: "object";
+    properties: Record<string, unknown>;
+    required: string[];
+  };
+}
+
+export interface ProviderConfig {
+  /** Which model, and everything the runtime needs to know about it. */
+  spec: ModelSpec;
+  maxTokens: number;
+  /** Controls thinking depth and spend. */
+  effort: Effort;
+  /**
+   * Summarized thinking is opt-in: the default returns thinking blocks with
+   * empty text, which to a user looks like a long pause before any output.
+   */
+  thinkingDisplay: "summarized" | "omitted";
+}
+
+export const DEFAULT_PROVIDER: ProviderConfig = {
+  spec: CLAUDE_OPUS_5,
+  maxTokens: 16_000,
+  effort: "high",
+  thinkingDisplay: "summarized",
+};
+
+/**
+ * What the loop needs from a model, and the entire surface an adapter has to
+ * implement. Anything wider would be an Anthropic concept leaking into the
+ * contract; anything narrower could not report usage, which the whole design
+ * rests on measuring.
+ */
+/**
+ * A display increment. Adapters emit these through `onDelta`; the loop
+ * turns them into UI events. They never become log events -- a turn that
+ * landed N deltas in the log would project as N assistant messages and
+ * break prefix stability (P7).
+ *
+ * Shared by both adapters so the loop never sees an Anthropic or OpenAI
+ * wire name. Discard is the same channel: a retry or a refusal has to
+ * wipe what the user already saw, and inventing a second callback would
+ * let one path forget.
+ */
+export type StreamDelta =
+  | { kind: "text"; text: string }
+  | { kind: "thinking"; text: string }
+  | { kind: "discard" };
+
+export type OnDelta = (delta: StreamDelta) => void;
+
+export interface Provider {
+  readonly config: ProviderConfig;
+  send(
+    frozen: FrozenPrefix,
+    messages: readonly Message[],
+    node: number,
+    signal?: AbortSignal,
+    onDelta?: OnDelta,
+  ): Promise<Turn>;
+}
+
+/**
+ * The SDK methods this adapter actually calls.
+ *
+ * Structural rather than `Anthropic` so a test can inject a fake without
+ * constructing a client -- that would pull credentials and the SDK retry
+ * loop, which is the opposite of what a fake is for. Tests cannot import
+ * the SDK package (the boundary checker forbids package imports outside
+ * runtime/apps).
+ */
+/** The complete-message shape, also what a non-streaming test fake returns. */
+export interface AnthropicMessage {
+  stop_reason: string | null;
+  stop_details?: { category?: string | null; explanation?: string | null } | null;
+  content: Anthropic.ContentBlock[];
+  usage: {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens?: number | null;
+    cache_read_input_tokens?: number | null;
+  };
+}
+
+export interface AnthropicTransport {
+  messages: {
+    create(
+      params: Anthropic.MessageCreateParamsNonStreaming | Anthropic.MessageCreateParamsStreaming,
+      options?: { signal?: AbortSignal | null },
+    ): Promise<AnthropicMessage | AsyncIterable<unknown>>;
+  };
+}
+
+export interface Turn {
+  blocks: AssistantBlock[];
+  stopReason: string | null;
+  usage: UsageSample;
+}
+
+/** Thrown for a refusal, which arrives as HTTP 200 rather than an error. */
+export class RefusalError extends Error {
+  readonly category: string | null;
+  readonly explanation: string | null;
+
+  constructor(category: string | null, explanation: string | null) {
+    super(`model refused the request${category ? ` (${category})` : ""}`);
+    this.name = "RefusalError";
+    this.category = category;
+    this.explanation = explanation;
+  }
+}
+
+function buildAnthropicClient(
+  apiKey: string | undefined,
+  options: { fetch?: typeof fetch; oauth?: boolean },
+): AnthropicTransport {
+  if (options.oauth === true && apiKey) {
+    // authToken is Bearer. Passing apiKey here would send x-api-key, which
+    // an OAuth token is not accepted as.
+    return new Anthropic({
+      maxRetries: 0,
+      authToken: apiKey,
+      defaultHeaders: anthropicOAuthHeaders(),
+      ...(options.fetch ? { fetch: options.fetch } : {}),
+    });
+  }
+  return new Anthropic({
+    maxRetries: 0,
+    ...(apiKey ? { apiKey } : {}),
+    ...(options.fetch ? { fetch: options.fetch } : {}),
+  });
+}
+
+export class AnthropicProvider implements Provider {
+  readonly config: ProviderConfig;
+  private readonly client: AnthropicTransport;
+  private readonly retry: RetryPolicy;
+  private readonly onRetry: ((attempt: number, delayMs: number, error: unknown) => void) | undefined;
+
+  /**
+   * `apiKey` comes from the resolution chain when there is one. Omitting it
+   * falls back to the SDK's own lookup (environment, `ant auth login`
+   * profile), which is what makes a machine already set up for Claude work
+   * with no configuration at all.
+   */
+  constructor(
+    config: ProviderConfig = DEFAULT_PROVIDER,
+    apiKey?: string,
+    options: {
+      client?: AnthropicTransport;
+      retry?: RetryPolicy;
+      onRetry?: (attempt: number, delayMs: number, error: unknown) => void;
+      fetch?: typeof fetch;
+      /** OAuth access token: Bearer + oauth-2025-04-20, never x-api-key (D18). */
+      oauth?: boolean;
+    } = {},
+  ) {
+    this.config = config;
+    // maxRetries: 0 because this adapter retries. Leaving the SDK's own on
+    // would multiply the two -- four attempts becoming sixteen -- and the
+    // outer layer could neither see how long the inner one slept nor count
+    // it, so the usage report would quietly stop adding up. The SDK timer
+    // also ignores AbortSignal, so an outer wait is the only one Escape
+    // can actually cancel.
+    this.client = options.client ?? buildAnthropicClient(apiKey, options);
+    this.retry = options.retry ?? DEFAULT_RETRY;
+    this.onRetry = options.onRetry;
+  }
+
+  send(
+    frozen: FrozenPrefix,
+    messages: readonly Message[],
+    node: number,
+    signal?: AbortSignal,
+    onDelta?: OnDelta,
+  ): Promise<Turn> {
+    return withRetry(
+      () => this.attempt(frozen, messages, node, signal, onDelta),
+      this.retry,
+      undefined,
+      (attempt, delayMs, error) => {
+        // The next attempt starts from empty. Without this the UI concatenates
+        // two openings of the same sentence and has no sign a retry happened.
+        onDelta?.({ kind: "discard" });
+        this.onRetry?.(attempt, delayMs, error);
+      },
+      signal,
+    );
+  }
+
+  private async attempt(
+    frozen: FrozenPrefix,
+    messages: readonly Message[],
+    node: number,
+    signal?: AbortSignal,
+    onDelta?: OnDelta,
+  ): Promise<Turn> {
+    const started = Date.now();
+
+    const response = await this.client.messages.create(
+      {
+        model: this.config.spec.id,
+        max_tokens: this.config.maxTokens,
+        stream: true,
+        // One explicit breakpoint on the frozen prefix. It renders before
+        // messages, so this read point holds regardless of how the tail grows.
+        system: [
+          {
+            type: "text",
+            text: frozen.system,
+            cache_control: { type: "ephemeral" },
+          },
+        ],
+        // Auto-caching walks the breakpoint forward over the growing tail.
+        cache_control: { type: "ephemeral" },
+        tools: frozen.tools as Anthropic.Tool[],
+        // Only a reasoning model understands these. An older Claude, or an
+        // Anthropic-compatible endpoint serving some other model, answers
+        // them with a 400 or silently ignores them.
+        ...(this.config.spec.reasoning
+          ? { thinking: { type: "adaptive" as const, display: this.config.thinkingDisplay },
+              output_config: { effort: this.config.effort } }
+          : {}),
+        messages: messages.map(toWireMessage),
+      },
+      signal ? { signal } : undefined,
+    );
+
+    const assembled = isAsyncIterable(response)
+      ? await consumeAnthropicStream(response, onDelta)
+      : {
+          blocks: response.content.map(fromWireBlock),
+          stopReason: response.stop_reason,
+          stopDetails: response.stop_details ?? null,
+          usage: {
+            input_tokens: response.usage.input_tokens,
+            output_tokens: response.usage.output_tokens,
+            cache_creation_input_tokens: response.usage.cache_creation_input_tokens ?? 0,
+            cache_read_input_tokens: response.usage.cache_read_input_tokens ?? 0,
+          },
+        };
+
+    // A refusal is HTTP 200 with stop_reason "refusal", so content must not be
+    // trusted after it. Anything already painted has to go with it.
+    if (assembled.stopReason === "refusal") {
+      onDelta?.({ kind: "discard" });
+      const details = assembled.stopDetails;
+      throw new RefusalError(details?.category ?? null, details?.explanation ?? null);
+    }
+
+    return {
+      blocks: assembled.blocks,
+      stopReason: assembled.stopReason,
+      usage: {
+        ...assembled.usage,
+        node,
+        ms: Date.now() - started,
+      },
+    };
+  }
+}
+
+function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
+  return typeof value === "object" && value !== null && Symbol.asyncIterator in value;
+}
+
+interface AssembledTurn {
+  blocks: AssistantBlock[];
+  stopReason: string | null;
+  stopDetails: { category?: string | null; explanation?: string | null } | null;
+  usage: {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens: number;
+    cache_read_input_tokens: number;
+  };
+}
+
+interface UsageFields {
+  input_tokens?: number | null;
+  output_tokens?: number | null;
+  cache_creation_input_tokens?: number | null;
+  cache_read_input_tokens?: number | null;
+}
+
+function takeUsage(
+  into: AssembledTurn["usage"],
+  raw: UsageFields | undefined,
+): void {
+  if (raw === undefined) return;
+  if (raw.input_tokens != null) into.input_tokens = raw.input_tokens;
+  if (raw.output_tokens != null) into.output_tokens = raw.output_tokens;
+  if (raw.cache_creation_input_tokens != null) {
+    into.cache_creation_input_tokens = raw.cache_creation_input_tokens;
+  }
+  if (raw.cache_read_input_tokens != null) {
+    into.cache_read_input_tokens = raw.cache_read_input_tokens;
+  }
+}
+
+function parseToolInput(raw: string): unknown {
+  if (raw.length === 0) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return { __unparsed_arguments: raw };
+  }
+}
+
+/**
+ * Walks the SDK stream (or a test fake of the same events) into a Turn.
+ *
+ * Usage is the sum of message_start (input / cache) and message_delta
+ * (output, and any field a proxy omitted at start). Deltas go to onDelta
+ * as they arrive so the loop can paint before this function returns.
+ */
+async function consumeAnthropicStream(
+  stream: AsyncIterable<unknown>,
+  onDelta: OnDelta | undefined,
+): Promise<AssembledTurn> {
+  const content: Anthropic.ContentBlock[] = [];
+  const jsonBuf = new Map<number, string>();
+  const assembled: AssembledTurn = {
+    blocks: [],
+    stopReason: null,
+    stopDetails: null,
+    usage: {
+      input_tokens: 0,
+      output_tokens: 0,
+      cache_creation_input_tokens: 0,
+      cache_read_input_tokens: 0,
+    },
+  };
+
+  for await (const raw of stream) {
+    const event = raw as {
+      type?: string;
+      index?: number;
+      message?: { usage?: UsageFields };
+      content_block?: Anthropic.ContentBlock;
+      delta?: {
+        type?: string;
+        text?: string;
+        thinking?: string;
+        signature?: string;
+        partial_json?: string;
+        stop_reason?: string | null;
+        stop_details?: { category?: string | null; explanation?: string | null } | null;
+      };
+      usage?: UsageFields;
+    };
+
+    switch (event.type) {
+      case "message_start":
+        takeUsage(assembled.usage, event.message?.usage);
+        break;
+      case "content_block_start": {
+        const index = event.index ?? content.length;
+        if (event.content_block !== undefined) {
+          content[index] = { ...event.content_block } as Anthropic.ContentBlock;
+          if (event.content_block.type === "tool_use") jsonBuf.set(index, "");
+        }
+        break;
+      }
+      case "content_block_delta": {
+        const index = event.index ?? 0;
+        const delta = event.delta;
+        const block = content[index];
+        if (delta === undefined || block === undefined) break;
+        if (delta.type === "text_delta" && delta.text) {
+          if (block.type === "text") block.text += delta.text;
+          onDelta?.({ kind: "text", text: delta.text });
+        } else if (delta.type === "thinking_delta" && delta.thinking) {
+          if (block.type === "thinking") block.thinking += delta.thinking;
+          onDelta?.({ kind: "thinking", text: delta.thinking });
+        } else if (delta.type === "signature_delta" && delta.signature && block.type === "thinking") {
+          block.signature = (block.signature ?? "") + delta.signature;
+        } else if (delta.type === "input_json_delta" && delta.partial_json) {
+          jsonBuf.set(index, (jsonBuf.get(index) ?? "") + delta.partial_json);
+        }
+        break;
+      }
+      case "content_block_stop": {
+        const index = event.index ?? 0;
+        const block = content[index];
+        if (block?.type === "tool_use") {
+          block.input = parseToolInput(jsonBuf.get(index) ?? "");
+        }
+        break;
+      }
+      case "message_delta": {
+        if (event.delta?.stop_reason) assembled.stopReason = event.delta.stop_reason;
+        if (event.delta?.stop_details !== undefined) {
+          assembled.stopDetails = event.delta.stop_details;
+        }
+        takeUsage(assembled.usage, event.usage);
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  assembled.blocks = content.filter((b) => b !== undefined).map(fromWireBlock);
+  return assembled;
+}
+
+function toWireMessage(m: Message): Anthropic.MessageParam {
+  return {
+    role: m.role,
+    content: m.content.map(toWireBlock) as Anthropic.ContentBlockParam[],
+  };
+}
+
+function toWireBlock(b: ContentBlock): unknown {
+  switch (b.type) {
+    case "text":
+      return { type: "text", text: b.text };
+    case "thinking":
+      // Verbatim. Reconstructing the block would drop its signature and the
+      // next request would be rejected.
+      return b.raw;
+    case "tool_use":
+      return { type: "tool_use", id: b.id, name: b.name, input: b.input };
+    case "tool_result":
+      return {
+        type: "tool_result",
+        tool_use_id: b.tool_use_id,
+        content: b.content,
+        ...(b.is_error ? { is_error: true } : {}),
+      };
+    default:
+      return assertNever(b, "toWireBlock");
+  }
+}
+
+function fromWireBlock(b: Anthropic.ContentBlock): AssistantBlock {
+  switch (b.type) {
+    case "text":
+      return { type: "text", text: b.text };
+    case "thinking":
+      // `raw` is what goes back to the API; `text` is only for display.
+      return { type: "thinking", text: b.thinking, raw: b };
+    case "redacted_thinking":
+      return { type: "thinking", text: "", raw: b };
+    case "tool_use":
+      return { type: "tool_use", call_id: b.id, name: b.name, input: b.input };
+    default:
+      // Server-tool blocks land here. They are kept verbatim as thinking-like
+      // opaque content so a replay stays byte-identical, rather than being
+      // dropped and breaking the turn.
+      return { type: "thinking", text: "", raw: b };
+  }
+}