@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/lib/index.js

@@ -0,0 +1,61 @@
+/**
+ * `@sixthsummit/ship-api` — public API barrel for ShipAPI v4.
+ *
+ * This is the canonical entry point for consumer apps. The framework
+ * exports a curated, semver-stable surface here; deep-path imports
+ * (`@sixthsummit/ship-api/http/middleware/...`) are still available
+ * but NOT covered by semver — they're for internal cross-module use
+ * and advanced consumers who need primitives the barrel doesn't yet
+ * surface.
+ *
+ * The `@sixthsummit/ship-api/client` subpath remains a separate
+ * lightweight bundle for typed-client consumers (web / mobile) that
+ * shouldn't pull in the framework's runtime deps. Import from there:
+ *
+ *   import { hc } from "@sixthsummit/ship-api/client";
+ *   import type { ShipApiClient } from "@my-org/api";
+ */
+export { ApplicationCompilationError, anyPermission, authenticatedAccess, checkOperationAccess, compileApp, createExecutor, createTenantBypassAuthority, createTenantScopeAuthority, defineActorResolver, defineApp, defineModule, defineOperation, defineProvider, dependency, effectDependency, InvalidModuleDefinitionError, InvalidOperationDefinitionError, InvalidProviderDefinitionError, isActorResolution, isActorResolver, isEffectDependencyToken, isExplicitOperationResponse, isOperationActor, isOperationIdentity, isTenantBypass, isTenantScope, isUnitOfWork, isUnitOfWorkDependencyToken, normalizeActorResolution, normalizeOperationActor, OperationExecutionError, OperationFailure, operationActor, operationError, operationFailure, operationIdentity, optionalIdentityAccess, permission, permissionSnapshot, publicAccess, respond, TenantCapabilityError, unitOfWorkDependency, valueProvider, } from "./kernel/index.js";
+export { createHonoAdapter, defineHonoCredentialAdapter, HonoAdapterError, honoAuthProvider, http, InvalidHttpTransportError, isHonoCredentialAdapter, isHttpTransport, requestHeadersCredential, } from "./hono/index.js";
+export { createApp, createModuleApp } from "./http/app/createApp.js";
+export { registerErrorHandlers } from "./http/app/errors.js";
+export { apiKey } from "./http/middleware/apiKey.js";
+export { csrf } from "./http/middleware/csrf.js";
+export { httpLogger } from "./http/middleware/httpLogger.js";
+export { idempotency } from "./http/middleware/idempotency.js";
+export { rateLimit } from "./http/middleware/rateLimit.js";
+export { AUTH_CONTEXT_KEYS, requireAuth } from "./http/middleware/requireAuth.js";
+export { requirePermission } from "./http/middleware/requirePermission.js";
+export { resolveTenant } from "./http/middleware/resolveTenant.js";
+export { streamSSE } from "./http/streaming/sse.js";
+export { streamLLM } from "./http/streaming/streamLLM.js";
+export { parseUpload } from "./http/utils/uploads.js";
+export { validate } from "./http/utils/validate.js";
+export { parseWebhook } from "./http/utils/webhooks.js";
+// ─── Error taxonomy ────────────────────────────────────────────────
+export { AppError, AuthenticationError, AuthorizationError, BadRequestError, ConflictError, InternalServerError, NotFoundError, RateLimitError, ServiceUnavailableError, ValidationError, } from "./http/errors/index.js";
+export { FirebaseAuthProvider, firebaseAuth } from "./app/auth/adapters/firebase.js";
+export { getRequestContext } from "./app/context/RequestContext.js";
+export { baseFields, baseFieldsTimestampsOnly } from "./app/db/baseFields.js";
+// `DslQueryFilter` (the DSL filter shape) lives in app/db/QueryOptions.js and
+// is intentionally NOT re-exported here — it's the ORM-translation detail, not
+// the common surface. Consumers driving the DSL directly import it from the
+// subpath:
+//   import type { DslQueryFilter } from "@sixthsummit/ship-api/app/db/QueryOptions";
+// The barrel re-exports the lifecycle-hook `QueryFilter` below (the common one).
+export { isQueryOperator, QUERY_OPERATORS } from "./app/db/QueryOptions.js";
+export { tenantScoped } from "./app/db/tenantScoped.js";
+export { RollbackError, withTransaction } from "./app/db/transaction.js";
+export { DrizzleEntityService } from "./app/services/DrizzleEntityService.js";
+export { composeHooks } from "./app/services/hooks/LifecycleHooks.js";
+export { cached, InMemoryCache, RedisCache } from "./app/services/cache/index.js";
+// ─── Redis provider ────────────────────────────────────────────────
+export { RedisProvider } from "./app/services/RedisProvider.js";
+export { defineJob, JobRegistry, JobsManager, jobRegistry } from "./app/services/jobs/index.js";
+export { CRON_QUEUE, defineCron } from "./app/services/cron/index.js";
+export { HealthCheckRegistry, healthCheckRegistry } from "./app/health/HealthCheck.js";
+export { redisHealthCheck } from "./app/health/redisHealthCheck.js";
+export { hasHealthRoutes, registerHealthRoutes } from "./http/app/health.js";
+export { routeRegistry } from "./app/registry/routes.js";
+export { defineEnv } from "./app/utils/defineEnv.js";
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

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

package/lib/kernel/index.d.ts

@@ -0,0 +1,3 @@
+/** @deprecated Import the redesign kernel from `@sixthsummit/ship-core`. */
+export * from "@sixthsummit/ship-core";
+//# sourceMappingURL=index.d.ts.map

package/lib/kernel/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/kernel/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,cAAc,wBAAwB,CAAC"}

package/lib/kernel/index.js

@@ -0,0 +1,3 @@
+/** @deprecated Import the redesign kernel from `@sixthsummit/ship-core`. */
+export * from "@sixthsummit/ship-core";
+//# sourceMappingURL=index.js.map

package/lib/kernel/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/kernel/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,cAAc,wBAAwB,CAAC"}

package/lib/libraries/ai/CHANGELOG.md

@@ -0,0 +1,17 @@
+# `ai` library — changelog
+
+The `ai` library is **versioned independently of the framework core** (AI-A3 / A2-11): the AI substrate churns fastest, so it bumps on its own schedule without dragging the stable framework version. The current version lives in `library.json#version` and is stamped into a consumer's `src/lib/ai/.ship-lib.json` on `ship-api add -l ai` (so staleness is detectable and `ship-api update` has an anchor).
+
+**Versioning rule:** bump `library.json#version` on any meaningful change to the `ai` surface. Pre-1.0, breaking changes bump the **minor**; additive/fix changes bump the **patch**. This is decoupled from the framework's `4.x` line.
+
+## 0.2.0
+
+Part II AI-library refinement (alpha-window, deliberate).
+
+- **AI-R1** — the `LLMProvider` seam is now genuinely pass-through, not lowest-common-denominator: `CompleteResult` / `StreamStopEvent` carry `raw` + `providerExtras`, `TokenUsage` carries `reasoningTokens` + `raw`, both adapters populate them (Anthropic thinking/citations/server-tool-use; OpenAI refusal/reasoning tokens), and `agentLoop` / `retrieveAndAnswer` no longer drop `providerOptions` / `metadata`. Additive-optional.
+- **AI-R2** (breaking) — `agentLoop` moved off the stable barrel to `@sixthsummit/ship-api/libraries/ai/experimental`; it carries no stability promise and is expected to be superseded by MCP / provider-native agent runtimes. `defineTool` / `toolRegistry` stay on the stable barrel.
+- **AI-R3** — `HeuristicTokenizer` / `countMessageTokens` deprecated (token truth is the provider response `usage`); added thin `estimateTokens` / `estimateMessageTokens` for pre-call prompt-fit / rate-limit budgeting. The `Tokenizer` interface is unchanged.
+
+## 0.1.0
+
+Initial `ai` library: the `LLMProvider` interface + Anthropic & OpenAI adapters, `defineTool` / `toolRegistry`, `agentLoop`, `completeStructured`, the `definePrompt` prompt registry, the `retrieveAndAnswer` RAG pipeline, and a pluggable `Tokenizer`.

package/lib/libraries/ai/README.md

@@ -0,0 +1,164 @@
+# `libraries/ai/` — LLM helper library
+
+The framework's defining differentiator. Provider-agnostic LLM tooling that consumers compose into their app: provider adapters (Anthropic + OpenAI today), prompt registry, tool-calling, agent loop, structured outputs, RAG, token counting.
+
+> **Install via**: `ship-api add -l ai`. The library itself takes **no** SDK runtime dependency — concrete provider adapters are opt-in (install only the SDK for the providers you use).
+
+## What's inside
+
+```
+libraries/ai/
+├── adapters/
+│   ├── LLMProvider.ts           — pluggable provider contract
+│   ├── AnthropicAdapter.ts      — wraps @anthropic-ai/sdk
+│   └── OpenAIAdapter.ts         — wraps openai
+├── tools/
+│   └── defineTool.ts            — Zod schema → typed handler + ToolRegistry
+├── loop/
+│   └── agentLoop.ts             — model→tool→model cycle with retry budget + signal honoring
+├── structured/
+│   └── completeStructured.ts    — Zod-typed single-shot via synthetic-tool pattern
+├── prompts/
+│   └── definePrompt.ts          — versioned prompt primitive + PromptRegistry
+├── rag/
+│   └── retrieveAndAnswer.ts     — pluggable VectorStore + LLMProvider RAG driver
+├── tokens/
+│   └── Tokenizer.ts             — pluggable tokenizer + HeuristicTokenizer baseline
+├── types.ts                     — cross-provider lingua franca
+└── index.ts                     — public barrel
+```
+
+## Quick reference
+
+### Provider-portable completion
+
+```ts
+import { AnthropicAdapter } from "@sixthsummit/ship-api/libraries/ai";
+
+const llm = new AnthropicAdapter({ apiKey: env.ANTHROPIC_API_KEY });
+
+const result = await llm.complete({
+  model: "claude-opus-4-7",
+  system: "Be concise.",
+  messages: [{ role: "user", content: "What is 2+2?" }],
+});
+console.log(result.text); // "4"
+```
+
+Swap `AnthropicAdapter` for `OpenAIAdapter` and the same call site works — provider-specific tunables ride on `providerOptions` so the cross-provider surface stays narrow.
+
+### Tool calling
+
+```ts
+import { defineTool, toolRegistry } from "@sixthsummit/ship-api/libraries/ai";
+// agentLoop is experimental (AI-R2) — no stability promise; the hand-rolled
+// loop is expected to be superseded by MCP / provider-native agent runtimes.
+import { agentLoop } from "@sixthsummit/ship-api/libraries/ai/experimental";
+import { z } from "zod";
+
+const getWeather = defineTool({
+  name: "get_weather",
+  description: "Look up current weather for a city",
+  schema: z.object({ city: z.string() }),
+  handler: async ({ city }) => fetchWeather(city),
+});
+
+const result = await agentLoop({
+  llm,
+  tools: toolRegistry(getWeather),
+  model: "claude-opus-4-7",
+  messages: [{ role: "user", content: "What's the weather in Paris?" }],
+  maxIterations: 5,
+});
+console.log(result.finalText);
+```
+
+### Structured outputs
+
+```ts
+import { completeStructured } from "@sixthsummit/ship-api/libraries/ai";
+import { z } from "zod";
+
+const { data } = await completeStructured({
+  llm,
+  schema: z.object({
+    sentiment: z.enum(["positive", "neutral", "negative"]),
+    confidence: z.number().min(0).max(1),
+  }),
+  model: "claude-opus-4-7",
+  messages: [{ role: "user", content: "I love this product!" }],
+});
+// data: { sentiment: "positive", confidence: 0.95 }
+```
+
+### RAG
+
+```ts
+import { retrieveAndAnswer } from "@sixthsummit/ship-api/libraries/ai";
+
+// Bring your own VectorStore — interface-only; no library coupling.
+const store: VectorStore = {
+  name: "weaviate",
+  async search({ query, topK }) {
+    /* ... */
+  },
+};
+
+const { answer, sources } = await retrieveAndAnswer({
+  llm,
+  vectorStore: store,
+  query: "What is the capital of France?",
+  topK: 5,
+  model: "claude-opus-4-7",
+});
+```
+
+### Streaming
+
+```ts
+import { streamLLM } from "@sixthsummit/ship-api";
+
+app.post("/chat", validate("json", schema), async (c) => {
+  const { prompt } = c.req.valid("json");
+  const stream = llm.streamComplete({
+    model: "claude-opus-4-7",
+    messages: [{ role: "user", content: prompt }],
+  });
+  return streamLLM(c, stream); // → SSE; client disconnect cancels upstream
+});
+```
+
+### Versioned prompts
+
+```ts
+import { definePrompt, PromptRegistry } from "@sixthsummit/ship-api/libraries/ai";
+
+const greetPrompt = definePrompt({
+  id: "greetings.welcome",
+  version: 3,
+  template: "Hello, {{name}}! Welcome to {{appName}}.",
+  schema: z.object({ name: z.string(), appName: z.string() }),
+});
+
+greetPrompt.render({ name: "Ada", appName: "ShipAPI" });
+// "Hello, Ada! Welcome to ShipAPI."
+```
+
+CI lint flags un-versioned changes — bumping `version` on every meaningful change makes the change auditable and lets eval suites pin to a known-good version.
+
+## Conventions
+
+- **The library never imports a provider SDK directly.** Adapters import the SDK they wrap; consumers install only the SDK for the providers they use.
+- **Provider-specific tunables ride in `providerOptions` / `providerExtras`** so the cross-provider surface stays narrow.
+- **Tools must be idempotent.** The agent loop's at-least-once delivery semantics mean a handler may be re-invoked after a crash or retry. Use `dedupeKey` for downstream deduplication where supported.
+- **Streaming abort honored end-to-end.** Client disconnect propagates through `streamLLM` → `iterator.return()` → upstream provider stream cancellation.
+
+## Versioning
+
+This library is **versioned independently of the framework core** (AI-A3): the AI substrate moves fastest, so it bumps on its own schedule via `library.json#version` without dragging the stable `4.x` framework version. On `ship-api add -l ai` the vendored version is stamped into `src/lib/ai/.ship-lib.json`, so staleness is detectable and `ship-api update` has an anchor to diff against. **Bump `library.json#version` on any meaningful change** — pre-1.0, breaking changes bump the minor, additive/fix changes bump the patch. See [`CHANGELOG.md`](./CHANGELOG.md).
+
+## See also
+
+- [Plan §G](#) (LLM helpers section in the master plan)
+- [v4 status](../../docs/V4_STATUS.md)
+- [AGENTS.md](../../AGENTS.md)

package/lib/libraries/ai/adapters/AnthropicAdapter.ts

@@ -0,0 +1,382 @@
+import Anthropic from "@anthropic-ai/sdk";
+import type {
+  Message as AnthropicMessage,
+  Tool as AnthropicTool,
+  ToolChoice as AnthropicToolChoice,
+  MessageCreateParamsBase,
+  MessageCreateParamsNonStreaming,
+  MessageCreateParamsStreaming,
+  MessageParam,
+  RawMessageStreamEvent,
+  ToolUseBlock,
+} from "@anthropic-ai/sdk/resources/messages/messages.js";
+import type {
+  CompleteOptions,
+  CompleteResult,
+  Message,
+  MessageContentPart,
+  StopReason,
+  StreamCompleteOptions,
+  StreamEvent,
+  TokenUsage,
+  ToolChoice,
+  ToolDefinition,
+} from "../types.js";
+import type { LLMProvider } from "./LLMProvider.js";
+
+/**
+ * Concrete `LLMProvider` implementation backed by `@anthropic-ai/sdk`.
+ *
+ * Translation surface:
+ *   - Cross-provider `Message` (text-or-content-parts) → Anthropic
+ *     `MessageParam[]` (top-level `system` extracted out per API
+ *     convention).
+ *   - `ToolDefinition` → Anthropic `Tool` (passes `inputSchema` through
+ *     as `input_schema` — both are JSON Schema).
+ *   - Anthropic `Message` response → `CompleteResult` with normalized
+ *     `StopReason` + `TokenUsage` (cache reads/creation surfaced when
+ *     present so cost trackers can see them).
+ *   - Anthropic `RawMessageStreamEvent` → normalized `StreamEvent`
+ *     stream — buffers tool-use input JSON deltas and emits the parsed
+ *     object on `content_block_stop` so consumers don't have to
+ *     re-implement the buffer.
+ *
+ * Constructor takes either an `apiKey` (the common case — instantiates
+ * the SDK internally) or a pre-built `client` (tests inject a stub
+ * implementing `client.messages.create(...)`; lets us drive end-to-end
+ * translation without monkey-patching the SDK module).
+ *
+ * Error normalization across providers lands in a later commit (along
+ * with `LLMProviderError`); for now SDK errors propagate as-is.
+ *
+ * Default model: `claude-opus-4-7` (the most capable Claude as of v4
+ * launch). Callers override per request via `opts.model`.
+ */
+
+export interface AnthropicAdapterOptions {
+  /** Anthropic API key. Required unless `client` is supplied. */
+  apiKey?: string;
+  /** Override the default Anthropic API base URL. */
+  baseURL?: string;
+  /** Forwarded as `defaultHeaders` to the SDK. */
+  defaultHeaders?: Record<string, string>;
+  /**
+   * Pre-built / stubbed SDK client. When supplied, `apiKey` / `baseURL`
+   * are ignored — useful for tests and for shared client reuse.
+   */
+  client?: AnthropicMessagesClient;
+  /** Default `max_tokens` when caller doesn't supply one. Defaults 4096. */
+  defaultMaxTokens?: number;
+}
+
+/**
+ * Structural slice of `Anthropic` we actually call — narrows what tests
+ * have to stub. The real `Anthropic` client satisfies this trivially.
+ */
+export interface AnthropicMessagesClient {
+  messages: {
+    create(
+      body: MessageCreateParamsNonStreaming,
+      options?: { signal?: AbortSignal },
+    ): Promise<AnthropicMessage>;
+    create(
+      body: MessageCreateParamsStreaming,
+      options?: { signal?: AbortSignal },
+    ): Promise<AsyncIterable<RawMessageStreamEvent>>;
+    create(
+      body: MessageCreateParamsBase,
+      options?: { signal?: AbortSignal },
+    ): Promise<AnthropicMessage | AsyncIterable<RawMessageStreamEvent>>;
+  };
+}
+
+const DEFAULT_MAX_TOKENS = 4096;
+const DEFAULT_MODEL = "claude-opus-4-7";
+
+export class AnthropicAdapter implements LLMProvider {
+  readonly name = "anthropic";
+
+  private readonly client: AnthropicMessagesClient;
+  private readonly defaultMaxTokens: number;
+
+  constructor(opts: AnthropicAdapterOptions = {}) {
+    if (opts.client) {
+      this.client = opts.client;
+    } else {
+      if (!opts.apiKey) {
+        throw new Error("AnthropicAdapter requires `apiKey` or a pre-built `client`");
+      }
+      this.client = new Anthropic({
+        apiKey: opts.apiKey,
+        baseURL: opts.baseURL,
+        defaultHeaders: opts.defaultHeaders,
+      }) as unknown as AnthropicMessagesClient;
+    }
+    this.defaultMaxTokens = opts.defaultMaxTokens ?? DEFAULT_MAX_TOKENS;
+  }
+
+  async complete(opts: CompleteOptions): Promise<CompleteResult> {
+    const body = this.buildRequestBody(opts, false) as MessageCreateParamsNonStreaming;
+    const response = (await this.client.messages.create(body, {
+      signal: opts.signal,
+    })) as AnthropicMessage;
+    return this.translateResponse(response);
+  }
+
+  async *streamComplete(opts: StreamCompleteOptions): AsyncIterable<StreamEvent> {
+    const body = this.buildRequestBody(opts, true) as MessageCreateParamsStreaming;
+    const stream = (await this.client.messages.create(body, {
+      signal: opts.signal,
+    })) as AsyncIterable<RawMessageStreamEvent>;
+
+    // Indexed buffers: Anthropic identifies content blocks by `index` (a
+    // turn-local integer); we map index → adapter-issued ID + buffered
+    // input JSON for tool-use blocks.
+    const blocks = new Map<
+      number,
+      { kind: "text" } | { kind: "tool_use"; id: string; name: string; jsonBuffer: string }
+    >();
+    let stopReason: StopReason = "unknown";
+    let stopSequence: string | undefined;
+    let usage: TokenUsage = { inputTokens: 0, outputTokens: 0 };
+
+    for await (const event of stream) {
+      switch (event.type) {
+        case "message_start": {
+          const msg = event.message;
+          usage = translateUsage(msg.usage);
+          yield { type: "start", id: msg.id, model: msg.model };
+          break;
+        }
+        case "content_block_start": {
+          const block = event.content_block;
+          if (block.type === "text") {
+            blocks.set(event.index, { kind: "text" });
+          } else if (block.type === "tool_use") {
+            blocks.set(event.index, {
+              kind: "tool_use",
+              id: block.id,
+              name: block.name,
+              jsonBuffer: "",
+            });
+            yield { type: "tool_use_start", id: block.id, name: block.name };
+          }
+          // Other block kinds (thinking, server_tool_use, …) are not yet
+          // surfaced through the cross-provider stream — adapters can
+          // expand the StreamEvent union in a later commit.
+          break;
+        }
+        case "content_block_delta": {
+          const block = blocks.get(event.index);
+          if (!block) break;
+          const delta = event.delta;
+          if (delta.type === "text_delta" && block.kind === "text") {
+            yield { type: "text_delta", delta: delta.text };
+          } else if (delta.type === "input_json_delta" && block.kind === "tool_use") {
+            block.jsonBuffer += delta.partial_json;
+            yield {
+              type: "tool_input_delta",
+              id: block.id,
+              partialJson: delta.partial_json,
+            };
+          }
+          break;
+        }
+        case "content_block_stop": {
+          const block = blocks.get(event.index);
+          if (block?.kind === "tool_use") {
+            const input = parseToolInput(block.jsonBuffer);
+            yield { type: "tool_use_end", id: block.id, input };
+          }
+          blocks.delete(event.index);
+          break;
+        }
+        case "message_delta": {
+          if (event.delta.stop_reason) stopReason = translateStopReason(event.delta.stop_reason);
+          if (event.delta.stop_sequence) stopSequence = event.delta.stop_sequence;
+          // Output tokens accumulate in message_delta's usage.
+          if (event.usage) {
+            usage = {
+              ...usage,
+              outputTokens: event.usage.output_tokens,
+            };
+          }
+          break;
+        }
+        case "message_stop": {
+          yield { type: "stop", stopReason, stopSequence, usage };
+          break;
+        }
+      }
+    }
+  }
+
+  // --- Translation helpers ------------------------------------------------
+
+  private buildRequestBody(
+    opts: CompleteOptions,
+    stream: boolean,
+  ): MessageCreateParamsBase & { stream?: boolean } {
+    const body: MessageCreateParamsBase & { stream?: boolean } = {
+      model: opts.model || DEFAULT_MODEL,
+      messages: opts.messages.map(toAnthropicMessage),
+      max_tokens: opts.maxTokens ?? this.defaultMaxTokens,
+    };
+    if (opts.system) body.system = opts.system;
+    if (opts.temperature !== undefined) body.temperature = opts.temperature;
+    if (opts.stopSequences?.length) body.stop_sequences = opts.stopSequences;
+    if (opts.tools?.length) body.tools = opts.tools.map(toAnthropicTool);
+    if (opts.toolChoice) body.tool_choice = toAnthropicToolChoice(opts.toolChoice);
+    if (opts.metadata) body.metadata = opts.metadata as { user_id?: string };
+    if (opts.providerOptions) Object.assign(body, opts.providerOptions);
+    if (stream) body.stream = true;
+    return body;
+  }
+
+  private translateResponse(response: AnthropicMessage): CompleteResult {
+    const content: MessageContentPart[] = [];
+    const extraBlocks: unknown[] = [];
+    for (const block of response.content) {
+      if (block.type === "text") {
+        content.push({ type: "text", text: block.text });
+      } else if (block.type === "tool_use") {
+        content.push({
+          type: "tool_use",
+          id: block.id,
+          name: block.name,
+          input: ((block as ToolUseBlock).input ?? {}) as Record<string, unknown>,
+        });
+      } else {
+        // Native blocks not on the cross-provider surface (thinking,
+        // redacted_thinking, citations, server_tool_use, …): pass them
+        // THROUGH `providerExtras` rather than drop them (AI-R1). The full
+        // untranslated response is also on `raw` below.
+        extraBlocks.push(block);
+      }
+    }
+    const text = content
+      .filter((p): p is { type: "text"; text: string } => p.type === "text")
+      .map((p) => p.text)
+      .join("");
+
+    const result: CompleteResult = {
+      id: response.id,
+      model: response.model,
+      content,
+      text,
+      stopReason: translateStopReason(response.stop_reason),
+      stopSequence: response.stop_sequence ?? undefined,
+      usage: translateUsage(response.usage),
+      raw: response,
+    };
+    if (extraBlocks.length > 0) result.providerExtras = { blocks: extraBlocks };
+    return result;
+  }
+}
+
+function toAnthropicMessage(msg: Message): MessageParam {
+  // Anthropic supports user/assistant roles in the messages array;
+  // tool-result messages are encoded as user messages with a
+  // `tool_result` content block per Anthropic API convention.
+  const role: MessageParam["role"] = msg.role === "assistant" ? "assistant" : "user";
+
+  if (typeof msg.content === "string") {
+    return { role, content: msg.content };
+  }
+
+  // biome-ignore lint/suspicious/useIterableCallbackReturn: MessageContentPart is a closed discriminated union and every member returns.
+  const blocks = msg.content.map((part) => {
+    switch (part.type) {
+      case "text":
+        return { type: "text", text: part.text } as const;
+      case "tool_use":
+        return {
+          type: "tool_use",
+          id: part.id,
+          name: part.name,
+          input: part.input,
+        } as const;
+      case "tool_result":
+        return {
+          type: "tool_result",
+          tool_use_id: part.toolUseId,
+          content: part.content,
+          is_error: part.isError ?? false,
+        } as const;
+      case "image":
+        return {
+          type: "image",
+          source: {
+            type: "base64" as const,
+            media_type: part.mediaType,
+            data: part.data,
+          },
+        } as const;
+    }
+  });
+
+  return { role, content: blocks } as MessageParam;
+}
+
+function toAnthropicTool(tool: ToolDefinition): AnthropicTool {
+  return {
+    name: tool.name,
+    description: tool.description,
+    input_schema: tool.inputSchema as AnthropicTool["input_schema"],
+  };
+}
+
+function toAnthropicToolChoice(choice: ToolChoice): AnthropicToolChoice {
+  switch (choice.type) {
+    case "auto":
+      return { type: "auto" };
+    case "any":
+      return { type: "any" };
+    case "none":
+      return { type: "none" };
+    case "tool":
+      return { type: "tool", name: choice.name };
+  }
+}
+
+function translateStopReason(
+  reason: AnthropicMessage["stop_reason"] | string | null | undefined,
+): StopReason {
+  switch (reason) {
+    case "end_turn":
+    case "max_tokens":
+    case "stop_sequence":
+    case "tool_use":
+      return reason;
+    case "refusal":
+      return "content_filter";
+    case "pause_turn":
+      // Treat extended-thinking pause as end-of-turn for cross-provider
+      // simplicity; consumers needing the distinction should target the
+      // Anthropic SDK directly.
+      return "end_turn";
+    default:
+      return "unknown";
+  }
+}
+
+function translateUsage(usage: AnthropicMessage["usage"]): TokenUsage {
+  return {
+    inputTokens: usage.input_tokens,
+    outputTokens: usage.output_tokens,
+    cacheReadInputTokens: usage.cache_read_input_tokens ?? undefined,
+    cacheCreationInputTokens: usage.cache_creation_input_tokens ?? undefined,
+    raw: usage,
+  };
+}
+
+function parseToolInput(buffer: string): Record<string, unknown> {
+  if (!buffer) return {};
+  try {
+    return JSON.parse(buffer) as Record<string, unknown>;
+  } catch {
+    // The Anthropic stream guarantees valid JSON when complete; if we
+    // get here the upstream call was canceled mid-stream.
+    return { __ship_api_partial: buffer };
+  }
+}