sailfork / t3code-github / .repos/ effect/ packages/ ai/ anthropic/ src/ AnthropicLanguageModel.ts

/**
 * The `AnthropicLanguageModel` module provides the Anthropic implementation of
 * Effect AI's `LanguageModel` service. It translates Effect AI prompts, tools,
 * files, reasoning content, and Anthropic-specific options into Messages API
 * requests, then converts normal and streaming Anthropic responses back into
 * Effect AI response content with provider metadata.
 *
 * @stability unstable
 * @since 4.0.0
 */
/** @effect-diagnostics preferSchemaOverJson:skip-file */
import * as AiError from "effect/ai/AiError"
import { toCodecAnthropic } from "effect/ai/AnthropicStructuredOutput"
import * as IdGenerator from "effect/ai/IdGenerator"
import * as LanguageModel from "effect/ai/LanguageModel"
import * as AiModel from "effect/ai/Model"
import type * as Prompt from "effect/ai/Prompt"
import type * as Response from "effect/ai/Response"
import * as Tool from "effect/ai/Tool"
import * as Arr from "effect/Array"
import * as Context from "effect/Context"
import * as DateTime from "effect/DateTime"
import * as Effect from "effect/Effect"
import * as Base64 from "effect/encoding/Base64"
import { dual } from "effect/Function"
import type * as HttpClientResponse from "effect/http/HttpClientResponse"
import * as Layer from "effect/Layer"
import * as Predicate from "effect/Predicate"
import * as Redactable from "effect/Redactable"
import * as Schema from "effect/Schema"
import * as SchemaAST from "effect/SchemaAST"
import * as Stream from "effect/Stream"
import type { Span } from "effect/Tracer"
import type { Mutable, Simplify } from "effect/Types"
import { AnthropicClient, type MessageStreamEvent } from "./AnthropicClient.ts"
import { addGenAIAnnotations } from "./AnthropicTelemetry.ts"
import * as AnthropicTool from "./AnthropicTool.ts"
import type * as Generated from "./Generated.ts"
import * as InternalUtilities from "./internal/utilities.ts"

/**
 * Known Anthropic Claude model identifiers exposed by the generated Anthropic schema.
 *
 * @stability unstable
 * @category models
 * @since 4.0.0
 */
export type Model = Extract<(typeof Generated.Model)["members"][number], { readonly literal: string }>["literal"]

// =============================================================================
// Configuration
// =============================================================================

/**
 * Context service for Anthropic language model configuration.
 *
 * **When to use**
 *
 * Use when you need scoped Anthropic model request defaults or per-operation
 * overrides from Effect context.
 *
 * **Details**
 *
 * The service stores request fields that are merged into Anthropic Messages API
 * requests. Scoped configuration overrides defaults supplied to `model`,
 * `make`, or `layer`.
 *
 * @stability unstable
 * @category services
 * @since 4.0.0
 */
export class Config extends Context.Service<
  Config,
  Simplify<
    & Partial<
      Omit<
        typeof Generated.BetaCreateMessageParams.Encoded,
        "messages" | "output_config" | "tools" | "tool_choice" | "stream"
      >
    >
    & {
      readonly output_config?: {
        readonly effort?: "low" | "medium" | "high" | null
      }
      /**
       * Disables Claude's ability to use multiple tools to respond to a query.
       */
      readonly disableParallelToolCalls?: boolean | undefined
      /**
       * Whether the model supports native structured outputs.
       *
       * Overrides automatic capability detection based on the model identifier.
       */
      readonly structuredOutputs?: boolean | undefined
      /**
       * Overrides model detection for mid-conversation system messages.
       * Set to `false` to send all instructions in the top-level `system` field.
       *
       * @see https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages
       */
      readonly midConversationSystemMessages?: boolean | undefined
      /**
       * Whether to use strict JSON schema validation for tool calls.
       *
       * **Details**
       *
       * Only applies to models that support structured outputs. Defaults to
       * `true` when structured outputs are supported.
       */
      readonly strictJsonSchema?: boolean | undefined
    }
  >
>()("@effect/ai-anthropic/AnthropicLanguageModel/Config") {}

// =============================================================================
// Provider Options / Metadata
// =============================================================================

declare module "effect/ai/Prompt" {
  /**
   * Anthropic-specific options for system messages.
   *
   * **Details**
   *
   * These options are used when translating system messages into Anthropic
   * request content.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface SystemMessageOptions extends ProviderOptions {
    readonly anthropic?: {
      /**
       * A breakpoint which marks the end of reusable content eligible for caching.
       */
      readonly cacheControl?: typeof Generated.CacheControlEphemeral.Encoded | null
    } | null
  }

  /**
   * Anthropic-specific options for user messages.
   *
   * **Details**
   *
   * These options are used when translating user messages into Anthropic
   * request content.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface UserMessageOptions extends ProviderOptions {
    readonly anthropic?: {
      /**
       * A breakpoint which marks the end of reusable content eligible for caching.
       */
      readonly cacheControl?: typeof Generated.CacheControlEphemeral.Encoded | null
    } | null
  }

  /**
   * Anthropic-specific options for assistant messages.
   *
   * **Details**
   *
   * These options are used when replaying assistant messages in Anthropic
   * conversation history.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface AssistantMessageOptions extends ProviderOptions {
    readonly anthropic?: {
      /**
       * A breakpoint which marks the end of reusable content eligible for caching.
       */
      readonly cacheControl?: typeof Generated.CacheControlEphemeral.Encoded | null
    } | null
  }

  /**
   * Anthropic-specific options for tool messages.
   *
   * **Details**
   *
   * These options are used when converting tool results into Anthropic user
   * content blocks.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface ToolMessageOptions extends ProviderOptions {
    readonly anthropic?: {
      /**
       * A breakpoint which marks the end of reusable content eligible for caching.
       */
      readonly cacheControl?: typeof Generated.CacheControlEphemeral.Encoded | null
    } | null
  }

  /**
   * Anthropic-specific options for text prompt parts.
   *
   * **When to use**
   *
   * Use when you use these options to control how text blocks are sent to Anthropic.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface TextPartOptions extends ProviderOptions {
    readonly anthropic?: {
      /**
       * A breakpoint which marks the end of reusable content eligible for caching.
       */
      readonly cacheControl?: typeof Generated.CacheControlEphemeral.Encoded | null
    } | null
  }

  /**
   * Anthropic-specific options for reasoning prompt parts.
   *
   * **Details**
   *
   * Preserves Claude thinking metadata when reasoning content is sent back to
   * Anthropic in later turns.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface ReasoningPartOptions extends ProviderOptions {
    readonly anthropic?: {
      readonly info?: {
        readonly type: "thinking"
        /**
         * Thinking content as an encrypted string, which is used to verify
         * that thinking content was indeed generated by Anthropic's API.
         */
        readonly signature: typeof Generated.ResponseThinkingBlock.fields.thinking.Encoded
      } | {
        readonly type: "redacted_thinking"
        /**
         * Thinking content which was flagged by Anthropic's safety systems, and
         * was therefore encrypted.
         */
        readonly redactedData: typeof Generated.ResponseRedactedThinkingBlock.fields.data.Encoded
      } | null
      /**
       * A breakpoint which marks the end of reusable content eligible for caching.
       */
      readonly cacheControl?: typeof Generated.CacheControlEphemeral.Encoded | null
    } | null
  }

  /**
   * Anthropic-specific options for file prompt parts.
   *
   * **Details**
   *
   * Controls document metadata, citations, and prompt caching for files sent to
   * Anthropic.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface FilePartOptions extends ProviderOptions {
    readonly anthropic?: {
      /**
       * A breakpoint which marks the end of reusable content eligible for caching.
       */
      readonly cacheControl?: typeof Generated.CacheControlEphemeral.Encoded | null
      /**
       * Whether or not citations should be enabled for the file part.
       */
      readonly citations?: typeof Generated.RequestCitationsConfig.Encoded | null
      /**
       * A custom title to provide to the document. If omitted, the file part's
       * `fileName` property will be used.
       */
      readonly documentTitle?: string | null
      /**
       * Additional context about the document that will be forwarded to the
       * large language model, but will not be used towards cited content.
       *
       * **When to use**
       *
       * Use when storing additional document metadata as text or stringified JSON.
       */
      readonly documentContext?: string | null
    } | null
  }

  /**
   * Anthropic-specific options for tool call prompt parts.
   *
   * **Details**
   *
   * Carries Anthropic tool caller metadata, MCP metadata, and cache control for
   * tool use blocks.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface ToolCallPartOptions extends ProviderOptions {
    readonly anthropic?: {
      readonly caller?: {
        readonly type: string
        readonly toolId?: string | null
      } | null
      /**
       * Contains details about the MCP tool that was called.
       */
      readonly mcp_tool?: {
        /**
         * The name of the MCP server
         */
        readonly server: string
      } | null
      /**
       * A breakpoint which marks the end of reusable content eligible for caching.
       */
      readonly cacheControl?: typeof Generated.CacheControlEphemeral.Encoded | null
    } | null
  }

  /**
   * Anthropic-specific options for tool result prompt parts.
   *
   * **Details**
   *
   * Carries Anthropic MCP metadata and controls prompt caching for tool result
   * content.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface ToolResultPartOptions extends ProviderOptions {
    readonly anthropic?: {
      /**
       * Contains details about the MCP tool that produced the result.
       */
      readonly mcp_tool?: {
        /**
         * The name of the MCP server
         */
        readonly server: string
      } | null
      /**
       * A breakpoint which marks the end of reusable content eligible for caching.
       */
      readonly cacheControl?: typeof Generated.CacheControlEphemeral.Encoded | null
    } | null
  }

  /**
   * Anthropic-specific options for tool approval request prompt parts.
   *
   * **Details**
   *
   * Controls prompt caching for human approval requests in conversations.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface ToolApprovalRequestPartOptions extends ProviderOptions {
    readonly anthropic?: {
      /**
       * A breakpoint which marks the end of reusable content eligible for caching.
       */
      readonly cacheControl?: typeof Generated.CacheControlEphemeral.Encoded | null
    } | null
  }

  /**
   * Anthropic-specific options for tool approval response prompt parts.
   *
   * **Details**
   *
   * Controls prompt caching for human approval responses in conversations.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface ToolApprovalResponsePartOptions extends ProviderOptions {
    readonly anthropic?: {
      /**
       * A breakpoint which marks the end of reusable content eligible for caching.
       */
      readonly cacheControl?: typeof Generated.CacheControlEphemeral.Encoded | null
    } | null
  }
}

declare module "effect/ai/Response" {
  /**
   * Anthropic metadata attached when a reasoning block begins.
   *
   * **Details**
   *
   * Includes Claude thinking metadata needed to continue reasoning-aware
   * conversations.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface ReasoningStartPartMetadata extends ProviderMetadata {
    readonly anthropic?: {
      readonly info?: {
        readonly type: "thinking"
        /**
         * Thinking content as an encrypted string, which is used to verify
         * that thinking content was indeed generated by Anthropic's API.
         */
        readonly signature: typeof Generated.ResponseThinkingBlock.fields.thinking.Encoded
      } | {
        readonly type: "redacted_thinking"
        /**
         * Thinking content which was flagged by Anthropic's safety systems, and
         * was therefore encrypted.
         */
        readonly redactedData: typeof Generated.ResponseRedactedThinkingBlock.fields.data.Encoded
      } | null
    } | null
  }

  /**
   * Anthropic metadata attached to streaming reasoning deltas.
   *
   * **Details**
   *
   * Includes the signature for streamed Claude thinking content when available.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface ReasoningDeltaPartMetadata extends ProviderMetadata {
    readonly anthropic?: {
      readonly info?: {
        readonly type: "thinking"
        /**
         * Thinking content as an encrypted string, which is used to verify
         * that thinking content was indeed generated by Anthropic's API.
         */
        readonly signature: typeof Generated.ResponseThinkingBlock.fields.thinking.Encoded
      } | null
    } | null
  }

  /**
   * Anthropic metadata attached to completed reasoning parts.
   *
   * **Details**
   *
   * Preserves Claude thinking or redacted thinking information for later turns.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface ReasoningPartMetadata extends ProviderMetadata {
    readonly anthropic?: {
      readonly info?: {
        readonly type: "thinking"
        /**
         * Thinking content as an encrypted string, which is used to verify
         * that thinking content was indeed generated by Anthropic's API.
         */
        readonly signature: typeof Generated.ResponseThinkingBlock.fields.thinking.Encoded
      } | {
        readonly type: "redacted_thinking"
        /**
         * Thinking content which was flagged by Anthropic's safety systems, and
         * was therefore encrypted.
         */
        readonly redactedData: typeof Generated.ResponseRedactedThinkingBlock.fields.data.Encoded
      } | null
    } | null
  }

  /**
   * Anthropic metadata attached to tool call response parts.
   *
   * **Details**
   *
   * Identifies Anthropic caller details and MCP tool metadata emitted by the
   * provider.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface ToolCallPartMetadata extends ProviderMetadata {
    readonly anthropic?: {
      readonly caller?: {
        readonly type: string
        readonly toolId?: string | null
      } | null
      /**
       * Contains details about the MCP tool that was called.
       */
      readonly mcp_tool?: {
        /**
         * The name of the MCP server
         */
        readonly server: string
      } | null
    } | null
  }

  /**
   * Anthropic metadata attached to tool result response parts.
   *
   * **Details**
   *
   * Identifies MCP tool metadata associated with provider-executed tool
   * results.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface ToolResultPartMetadata extends ProviderMetadata {
    readonly anthropic?: {
      /**
       * Contains details about the MCP tool that was called.
       */
      readonly mcp_tool?: {
        /**
         * The name of the MCP server
         */
        readonly server: string
      } | null
    } | null
  }

  /**
   * Anthropic metadata for document citations in model responses.
   *
   * **Details**
   *
   * Records the cited document span by character position or page number.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface DocumentSourcePartMetadata extends ProviderMetadata {
    readonly anthropic?: {
      readonly source: "document"
      readonly type: "char_location"
      /**
       * The text that was cited in the response.
       */
      readonly citedText: string
      /**
       * The 0-indexed starting position of the characters that were cited.
       */
      readonly startCharIndex: number
      /**
       * The exclusive ending position of the characters that were cited.
       */
      readonly endCharIndex: number
    } | {
      readonly source: "document"
      readonly type: "page_location"
      /**
       * The text that was cited in the response.
       */
      readonly citedText: string
      /**
       * The 1-indexed starting page of pages that were cited.
       */
      readonly startPageNumber: number
      /**
       * The exclusive ending position of the pages that were cited.
       */
      readonly endPageNumber: number
    } | null
  }

  /**
   * Anthropic metadata for URL and web citations in model responses.
   *
   * **Details**
   *
   * Records cited URL text or web-search source freshness information.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface UrlSourcePartMetadata extends ProviderMetadata {
    readonly anthropic?: {
      readonly source: "url"
      /**
       * Up to 150 characters of the text content that was referenced from the
       * URL source material.
       */
      readonly citedText: string
      /**
       * An internal reference that must be passed back to the Anthropic API
       * during multi-turn conversations.
       */
      readonly encryptedIndex: string
    } | {
      readonly source: "web"
      readonly pageAge: string | null
    } | null
  }

  /**
   * Anthropic metadata attached to the finish part of a response.
   *
   * **Details**
   *
   * Includes container state, context management information, stop details, and
   * token usage reported by Anthropic.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface FinishPartMetadata extends ProviderMetadata {
    readonly anthropic?: {
      readonly container: typeof Generated.BetaContainer.Encoded | null
      readonly contextManagement: typeof Generated.BetaResponseContextManagement.Encoded | null
      readonly stopSequence: string | null
      readonly usage: typeof Generated.BetaMessage.Encoded["usage"] | null
    } | null
  }

  /**
   * Anthropic metadata attached to error response parts.
   *
   * **Details**
   *
   * Includes the provider request identifier when Anthropic returns one.
   *
   * @stability unstable
   * @category models
   * @since 4.0.0
   */
  export interface ErrorPartMetadata extends ProviderMetadata {
    readonly anthropic?: {
      requestId?: string | null
    } | null
  }

  /**
   * Anthropic metadata attached to response metadata parts.
   *
   * **Details**
   *
   * Fallback blocks are stored in `anthropic.fallback`; the part's `modelId`
   * identifies the fallback model.
   *
   * @stability unstable
   * @category models
   * @since 4.0.3
   */
  export interface ResponseMetadataPartMetadata extends ProviderMetadata {
    readonly anthropic?: {
      readonly fallback?: typeof Generated.BetaResponseFallbackBlock.Encoded
    } | null
  }
}

// =============================================================================
// Language Model
// =============================================================================

/**
 * Creates an Anthropic model descriptor that can be provided with `Effect.provide`.
 *
 * **When to use**
 *
 * Use when you want an Anthropic Claude model value that carries provider and
 * model metadata and can be supplied directly to an Effect program.
 *
 * @see {@link layer} for creating a `LanguageModel.LanguageModel` layer directly
 * @see {@link make} for constructing the language model service effectfully
 *
 * @stability unstable
 * @category constructors
 * @since 4.0.0
 */
export const model = (
  model: (string & {}) | Model,
  config?: Omit<typeof Config.Service, "model">
): AiModel.Model<"anthropic", LanguageModel.LanguageModel, AnthropicClient> =>
  AiModel.make("anthropic", model, layer({ model, config }))

/**
 * Creates an Anthropic `LanguageModel` service from a model identifier and optional request defaults.
 *
 * **When to use**
 *
 * Use when you need to construct a `LanguageModel` value backed by
 * `AnthropicClient` inside an Effect.
 *
 * **Details**
 *
 * The returned effect requires `AnthropicClient`. Request defaults from the
 * `config` option are merged with any `Config` service in the context, with
 * context values taking precedence.
 *
 * @see {@link layer} for providing the service as a `Layer`
 * @see {@link model} for creating a model descriptor for `AiModel.provide`
 *
 * @stability unstable
 * @category constructors
 * @since 4.0.0
 */
export const make = Effect.fnUntraced(function*({ model, config: providerConfig }: {
  readonly model: (string & {}) | Model
  readonly config?: Omit<typeof Config.Service, "model"> | undefined
}): Effect.fn.Return<LanguageModel.LanguageModel, never, AnthropicClient> {
  const client = yield* AnthropicClient

  const makeConfig: Effect.Effect<typeof Config.Service & { readonly model: string }> = Effect.contextWith((services) =>
    Effect.succeed({
      model,
      ...providerConfig,
      ...Context.getOrUndefined(services, Config)
    })
  )

  const makeRequest = Effect.fnUntraced(
    function*<Tools extends ReadonlyArray<Tool.Any>>({ config, options, toolNameMapper }: {
      readonly config: typeof Config.Service & { readonly model: string }
      readonly options: LanguageModel.ProviderOptions
      readonly toolNameMapper: Tool.NameMapper<Tools>
    }): Effect.fn.Return<{
      readonly params: typeof Generated.BetaMessagesPostParams.Encoded
      readonly payload: typeof Generated.BetaCreateMessageParams.Encoded
    }, AiError.AiError> {
      const betas = new Set<string>()
      const capabilities = getConfigCapabilities(config)
      const { messages, system } = yield* prepareMessages({ betas, capabilities, options, toolNameMapper })
      const outputFormat = yield* getOutputFormat({ capabilities, options })
      const { tools, toolChoice } = yield* prepareTools({ betas, capabilities, config, options, toolNameMapper })
      const params: Mutable<typeof Generated.BetaMessagesPostParams.Encoded> = {}
      if (betas.size > 0) {
        params["anthropic-beta"] = Array.from(betas).join(",")
      }
      const {
        disableParallelToolCalls: _,
        output_config,
        strictJsonSchema: _strictJsonSchema,
        structuredOutputs: _structuredOutputs,
        midConversationSystemMessages: _midConversationSystemMessages,
        ...requestConfig
      } = config
      const payload: Mutable<typeof Generated.BetaCreateMessageParams.Encoded> = {
        ...requestConfig,
        max_tokens: requestConfig.max_tokens ?? capabilities.maxOutputTokens,
        messages,
        ...(Predicate.isNotUndefined(system) ? { system } : undefined),
        ...(Predicate.isNotUndefined(tools) ? { tools } : undefined),
        ...(Predicate.isNotUndefined(toolChoice) ? { tool_choice: toolChoice } : undefined)
      }
      const outputConfig: Mutable<typeof Generated.BetaCreateMessageParams.Encoded["output_config"]> = {}
      if (Predicate.isNotUndefined(outputFormat)) {
        outputConfig.format = outputFormat
      }
      if (Predicate.isNotUndefined(output_config?.effort)) {
        outputConfig.effort = output_config.effort
      }
      if (Object.keys(outputConfig).length > 0) {
        payload.output_config = outputConfig
      }
      return { params, payload }
    }
  )

  return yield* LanguageModel.make({
    codecTransformer: toCodecAnthropic,
    supportsSystemMessagesInHistory: Effect.map(
      makeConfig,
      (config) => getConfigCapabilities(config).supportsMidConversationSystemMessages
    ),
    generateText: Effect.fnUntraced(function*(options) {
      const config = yield* makeConfig
      const toolNameMapper = new Tool.NameMapper(options.tools)
      const request = yield* makeRequest({ config, options, toolNameMapper })
      annotateRequest(options.span, request.payload)
      const [rawResponse, response] = yield* client.createMessage(request)
      annotateResponse(options.span, rawResponse)
      return yield* makeResponse({ options, rawResponse, response, toolNameMapper })
    }),
    streamText: Effect.fnUntraced(function*(options) {
      const config = yield* makeConfig
      const toolNameMapper = new Tool.NameMapper(options.tools)
      const request = yield* makeRequest({ config, options, toolNameMapper })
      annotateRequest(options.span, request.payload)
      const [response, stream] = yield* client.createMessageStream(request)
      return yield* makeStreamResponse({ stream, response, options, toolNameMapper })
    }, (effect, options) =>
      effect.pipe(
        Stream.unwrap,
        Stream.map((response) => {
          annotateStreamResponse(options.span, response)
          return response
        })
      ))
  })
})

/**
 * Creates a layer for the Anthropic language model.
 *
 * **When to use**
 *
 * Use when composing application layers and you want Anthropic to satisfy
 * `LanguageModel.LanguageModel` while supplying `AnthropicClient` from another
 * layer.
 *
 * @see {@link make} for constructing the language model service effectfully
 * @see {@link model} for creating a model service directly
 *
 * @stability unstable
 * @category layers
 * @since 4.0.0
 */
export const layer = (options: {
  readonly model: (string & {}) | Model
  readonly config?: Omit<typeof Config.Service, "model"> | undefined
}): Layer.Layer<LanguageModel.LanguageModel, never, AnthropicClient> =>
  Layer.effect(LanguageModel.LanguageModel, make(options))

/**
 * Provides config overrides for Anthropic language model operations.
 *
 * **When to use**
 *
 * Use to apply Anthropic request configuration to one effect without changing
 * the model's default configuration.
 *
 * **Details**
 *
 * The overrides are merged with any existing `Config` service for the duration
 * of the supplied effect. Fields in `overrides` take precedence over existing
 * config, and the helper supports both `effect.pipe(withConfigOverride(overrides))`
 * and `withConfigOverride(effect, overrides)`.
 *
 * @see {@link Config} for available Anthropic request configuration fields
 *
 * @stability unstable
 * @category configuration
 * @since 4.0.0
 */
export const withConfigOverride: {
  (overrides: typeof Config.Service): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>
  <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service): Effect.Effect<A, E, Exclude<R, Config>>
} = dual<
  (
    overrides: typeof Config.Service
  ) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>,
  <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service) => Effect.Effect<A, E, Exclude<R, Config>>
>(2, (self, overrides) =>
  Effect.flatMap(
    Effect.serviceOption(Config),
    (config) =>
      Effect.provideService(self, Config, {
        ...(config._tag === "Some" ? config.value : {}),
        ...overrides
      })
  ))

// =============================================================================
// Prompt Conversion
// =============================================================================

const prepareMessages = Effect.fnUntraced(
  function*<Tools extends ReadonlyArray<Tool.Any>>({ betas, capabilities, options, toolNameMapper }: {
    readonly betas: Set<string>
    readonly capabilities: ModelCapabilities
    readonly options: LanguageModel.ProviderOptions
    readonly toolNameMapper: Tool.NameMapper<Tools>
  }): Effect.fn.Return<{
    readonly system: ReadonlyArray<typeof Generated.BetaRequestTextBlock.Encoded> | undefined
    readonly messages: ReadonlyArray<typeof Generated.BetaInputMessage.Encoded>
  }, AiError.AiError> {
    const groups = groupMessages(options.prompt)

    // A system message in history must directly follow a user turn and directly
    // precede an assistant turn or the end of the prompt, so later instructions
    // are held until the next assistant turn. If any of them cannot be placed
    // that way, every instruction goes in the top-level `system` field instead:
    // inline instructions override top-level ones, so mixing would reorder them.
    const inlineSystem = capabilities.supportsMidConversationSystemMessages &&
      groups.every((group, i) =>
        i === 0 || group.type !== "system" || groups[i - 1].type === "user" || groups[i + 1]?.type === "user"
      )

    const system: Array<typeof Generated.BetaRequestTextBlock.Encoded> = []
    const messages: Array<typeof Generated.BetaInputMessage.Encoded> = []
    let pendingSystem: Array<typeof Generated.BetaRequestTextBlock.Encoded> = []

    for (let i = 0; i < groups.length; i++) {
      const group = groups[i]
      const isLastGroup = i === groups.length - 1

      switch (group.type) {
        case "system": {
          const target = i === 0 || !inlineSystem ? system : pendingSystem
          for (const message of group.messages) {
            target.push({
              type: "text",
              text: message.content,
              cache_control: getCacheControl(message)
            })
          }
          break
        }

        case "user": {
          const content: Array<typeof Generated.BetaInputContentBlock.Encoded> = []

          for (const message of group.messages) {
            switch (message.role) {
              case "user": {
                for (let j = 0; j < message.content.length; j++) {
                  const part = message.content[j]
                  const isLastPart = j === message.content.length - 1

                  // Attempt to get the cache control from the part first. If
                  // the part does not have cache control defined and we are
                  // evaluating the last part for this message, also check the
                  // message for cache control.
                  const cacheControl = getCacheControl(part) ?? (
                    isLastPart ? getCacheControl(message) : null
                  )

                  switch (part.type) {
                    case "text": {
                      content.push({
                        type: "text",
                        text: part.text,
                        cache_control: cacheControl
                      })
                      break
                    }

                    case "file": {
                      content.push(yield* prepareFilePart(part, cacheControl, betas))
                      break
                    }
                  }
                }
                break
              }

              case "tool": {
                for (let j = 0; j < message.content.length; j++) {
                  const part = message.content[j]

                  // Skip evaluation of tool approval parts
                  if (part.type === "tool-approval-response") {
                    continue
                  }

                  const isLastPart = j === message.content.length - 1

                  // Attempt to get the cache control from the part first. If
                  // the part does not have cache control defined and we are
                  // evaluating the last part for this message, also check the
                  // message for cache control.
                  const cacheControl = getCacheControl(part) ?? (
                    isLastPart ? getCacheControl(message) : null
                  )

                  content.push({
                    type: "tool_result",
                    tool_use_id: part.id,
                    content: Predicate.isUndefined(part.modelOutput)
                      ? typeof part.result === "string" ? part.result : JSON.stringify(part.result)
                      : yield* prepareToolResultContent(part.modelOutput, betas),
                    is_error: part.isFailure,
                    cache_control: cacheControl
                  })
                }
              }
            }
          }

          messages.push({ role: "user", content })

          break
        }

        case "assistant": {
          if (pendingSystem.length > 0) {
            messages.push({ role: "system", content: pendingSystem })
            pendingSystem = []
          }

          const content: Array<typeof Generated.BetaInputContentBlock.Encoded> = []
          const mcpToolIds = new Set<string>()

          for (let j = 0; j < group.messages.length; j++) {
            const message = group.messages[j]
            const isLastMessage = j === group.messages.length - 1
            const messageStart = content.length

            for (let k = 0; k < message.content.length; k++) {
              const part = message.content[k]

              if (part.type === "file" || part.type === "tool-approval-request") {
                continue
              }

              const isLastPart = k === message.content.length - 1
              const partStart = content.length

              switch (part.type) {
                case "text": {
                  content.push({
                    type: "text",
                    // Anthropic does not allow trailing whitespace in assistant
                    // content blocks
                    text: isLastGroup && isLastMessage && isLastPart
                      ? part.text.trim()
                      : part.text
                  })
                  break
                }
                case "reasoning": {
                  // TODO: make sending reasoning configurable
                  const info = part.options.anthropic?.info
                  if (Predicate.isNotNullish(info)) {
                    if (info.type === "thinking") {
                      content.push({
                        type: "thinking",
                        thinking: part.text,
                        signature: info.signature
                      })
                    } else {
                      content.push({
                        type: "redacted_thinking",
                        data: info.redactedData
                      })
                    }
                  }
                  break
                }

                case "tool-call": {
                  if (part.providerExecuted) {
                    const toolName = toolNameMapper.getProviderName(part.name)

                    const isMcpTool = Predicate.isNotNullish(part.options.anthropic?.mcp_tool)

                    if (isMcpTool) {
                      const { server } = part.options.anthropic.mcp_tool

                      mcpToolIds.add(part.id)

                      content.push({
                        type: "mcp_tool_use",
                        id: part.id,
                        name: part.name,
                        input: part.params as any,
                        server_name: server
                      })
                    } else if (
                      toolName === "code_execution" &&
                      Predicate.hasProperty(part.params, "type") &&
                      (
                        part.params.type === "bash_code_execution" ||
                        part.params.type === "text_editor_code_execution"
                      )
                    ) {
                      content.push({
                        type: "server_tool_use",
                        id: part.id,
                        name: part.params.type,
                        input: part.params as any
                      })
                    } else if (
                      // code execution 20250825 programmatic tool calling:
                      // Strip the fake 'programmatic-tool-call' type before sending to Anthropic
                      toolName === "code_execution" &&
                      Predicate.hasProperty(part.params, "type") &&
                      part.params.type === "programmatic-tool-call"
                    ) {
                      const { type: _type, ...params } = part.params
                      content.push({
                        type: "server_tool_use",
                        id: part.id,
                        name: toolName,
                        input: params as any
                      })
                    } else {
                      if (
                        // code execution 20250522
                        toolName === "code_execution" ||
                        toolName === "tool_search_tool_regex" ||
                        toolName === "tool_search_tool_bm25" ||
                        toolName === "web_fetch" ||
                        toolName === "web_search"
                      ) {
                        content.push({
                          type: "server_tool_use",
                          id: part.id,
                          name: toolName,
                          input: part.params as any
                        })
                      }
                    }
                  } else {
                    // Extract caller info from provider options for programmatic tool calling
                    const options = part.options.anthropic
                    const caller = Predicate.isNotNullish(options?.caller)
                      ? (
                          options.caller.type === "code_execution_20250825" &&
                          Predicate.isNotNullish(options.caller.toolId)
                        )
                        ? {
                          type: "code_execution_20250825",
                          tool_id: options.caller.toolId
                        } as const
                        : options.caller.type === "direct"
                        ? {
                          type: "direct"
                        } as const
                        : undefined
                      : undefined

                    content.push({
                      type: "tool_use",
                      id: part.id,
                      name: toolNameMapper.getProviderName(part.name),
                      input: part.params as any,
                      ...(Predicate.isNotUndefined(caller) ? { caller } : undefined)
                    })
                  }

                  break
                }

                case "tool-result": {
                  const toolName = toolNameMapper.getProviderName(part.name)

                  if (mcpToolIds.has(part.id)) {
                    content.push({
                      type: "mcp_tool_result",
                      tool_use_id: part.id,
                      is_error: part.isFailure,
                      content: part.result as any
                    })
                    break
                  }

                  if (toolName === "code_execution" && Predicate.hasProperty(part.result, "type")) {
                    if (part.result.type === "code_execution_result") {
                      content.push({
                        type: "code_execution_tool_result",
                        tool_use_id: part.id,
                        content: part.result as any
                      })
                    } else if (
                      part.result.type === "bash_code_execution_result" ||
                      part.result.type === "bash_code_execution_tool_result_error"
                    ) {
                      content.push({
                        type: "bash_code_execution_tool_result",
                        tool_use_id: part.id,
                        content: part.result as any
                      })
                    } else if (
                      part.result.type === "text_editor_code_execution_tool_result" ||
                      part.result.type === "text_editor_code_execution_tool_result_error"
                    ) {
                      content.push({
                        type: "text_editor_code_execution_tool_result",
                        tool_use_id: part.id,
                        content: part.result as any
                      })
                    }
                    break
                  }

                  if (toolName === "web_fetch") {
                    content.push({
                      type: "web_fetch_tool_result",
                      tool_use_id: part.id,
                      content: part.result as any
                    })
                    break
                  }

                  if (toolName === "web_search") {
                    content.push({
                      type: "web_search_tool_result",
                      tool_use_id: part.id,
                      content: part.result as any
                    })
                    break
                  }

                  if (
                    toolName === "tool_search_tool_regex" ||
                    toolName === "tool_search_tool_bm25"
                  ) {
                    content.push({
                      type: "tool_search_tool_result",
                      tool_use_id: part.id,
                      content: Array.isArray(part.result)
                        ? { type: "tool_search_tool_search_result", tool_references: part.result }
                        : part.result as any
                    })
                    break
                  }

                  break
                }
              }

              setLastCacheControl(content, partStart, getCacheControl(part))
            }

            setLastCacheControl(content, messageStart, getCacheControl(message))
          }

          messages.push({ role: "assistant", content })

          break
        }
      }
    }

    if (pendingSystem.length > 0) {
      messages.push({ role: "system", content: pendingSystem })
    }

    return {
      system: system.length > 0 ? system : undefined,
      messages
    }
  }
)

// =============================================================================
// Tool Conversion
// =============================================================================

/**
 * Encoded Anthropic custom tool definition that can be sent in a Messages API request.
 *
 * **When to use**
 *
 * Use when you need to type or inspect the provider-specific request payload for
 * a custom Anthropic tool.
 *
 * **Details**
 *
 * This type aliases the encoded `Generated.BetaTool` schema used for Effect
 * user-defined and dynamic tools after conversion. It contains the tool `name`,
 * optional `description`, and `input_schema`, plus Anthropic-specific fields
 * such as `strict` and `cache_control`.
 *
 * @see {@link AnthropicProviderDefinedTool} for the request shape used by Anthropic built-in provider tools
 *
 * @stability unstable
 * @category tools
 * @since 4.0.0
 */
export type AnthropicUserDefinedTool = typeof Generated.BetaTool.Encoded

/**
 * Represents a provider-defined tool that can be passed to the Anthropic API.
 *
 * **Details**
 *
 * These include Anthropic's built-in tools like computer use, code execution,
 * web search, and text editing.
 *
 * @stability unstable
 * @category tools
 * @since 4.0.0
 */
export type AnthropicProviderDefinedTool =
  | typeof Generated.BetaBashTool_20241022.Encoded
  | typeof Generated.BetaBashTool_20250124.Encoded
  | typeof Generated.BetaCodeExecutionTool_20250522.Encoded
  | typeof Generated.BetaCodeExecutionTool_20250825.Encoded
  | typeof Generated.BetaComputerUseTool_20241022.Encoded
  | typeof Generated.BetaComputerUseTool_20250124.Encoded
  | typeof Generated.BetaComputerUseTool_20251124.Encoded
  | typeof Generated.BetaMemoryTool_20250818.Encoded
  | typeof Generated.BetaTextEditor_20241022.Encoded
  | typeof Generated.BetaTextEditor_20250124.Encoded
  | typeof Generated.BetaTextEditor_20250429.Encoded
  | typeof Generated.BetaTextEditor_20250728.Encoded
  | typeof Generated.BetaToolSearchToolBM25_20251119.Encoded
  | typeof Generated.BetaToolSearchToolRegex_20251119.Encoded
  | typeof Generated.BetaWebFetchTool_20250910.Encoded
  | typeof Generated.BetaWebSearchTool_20250305.Encoded

const prepareToolResultContent = Effect.fnUntraced(function*(
  modelOutput: ReadonlyArray<Prompt.ToolModelOutputPart>,
  betas: Set<string>
): Effect.fn.Return<
  | string
  | Array<
    | typeof Generated.BetaRequestTextBlock.Encoded
    | typeof Generated.BetaRequestImageBlock.Encoded
    | typeof Generated.BetaRequestDocumentBlock.Encoded
  >,
  AiError.AiError
> {
  if (modelOutput.length === 0) {
    return ""
  }
  const content: Array<
    | typeof Generated.BetaRequestTextBlock.Encoded
    | typeof Generated.BetaRequestImageBlock.Encoded
    | typeof Generated.BetaRequestDocumentBlock.Encoded
  > = []
  for (const part of modelOutput) {
    const cacheControl = getCacheControl(part)
    content.push(
      part.type === "text"
        ? { type: "text", text: part.text, cache_control: cacheControl }
        : yield* prepareFilePart(part, cacheControl, betas)
    )
  }
  return content
})

const getBase64Data = (data: string | Uint8Array): string =>
  typeof data === "string" ? data.replace(/^data:[^;]+;base64,/, "") : Base64.encode(data)

const prepareFilePart = Effect.fnUntraced(function*(
  part: Prompt.FilePart,
  cacheControl: typeof Generated.CacheControlEphemeral.Encoded | null,
  betas: Set<string>
): Effect.fn.Return<
  typeof Generated.BetaRequestImageBlock.Encoded | typeof Generated.BetaRequestDocumentBlock.Encoded,
  AiError.AiError
> {
  if (part.mediaType.startsWith("image/")) {
    const mediaType: typeof Generated.Base64ImageSource.Type["media_type"] =
      (part.mediaType === "image/*" ? "image/jpeg" : part.mediaType) as any

    const source = isUrlData(part.data)
      ? { type: "url", url: getUrlString(part.data) } as const
      : { type: "base64", media_type: mediaType, data: getBase64Data(part.data) } as const

    return { type: "image", source, cache_control: cacheControl }
  }

  if (part.mediaType === "application/pdf" || part.mediaType === "text/plain") {
    betas.add("pdfs-2024-09-25")

    const enableCitations = areCitationsEnabled(part)
    const documentOptions = getDocumentMetadata(part)

    const source = isUrlData(part.data)
      ? {
        type: "url",
        url: getUrlString(part.data)
      } as const
      : part.mediaType === "application/pdf"
      ? { type: "base64", media_type: "application/pdf", data: getBase64Data(part.data) } as const
      : {
        type: "text",
        media_type: "text/plain",
        data: typeof part.data === "string" ? part.data : new TextDecoder().decode(part.data)
      } as const

    return {
      type: "document",
      source,
      title: documentOptions?.title ?? part.fileName ?? null,
      cache_control: cacheControl,
      ...(documentOptions?.context ? { context: documentOptions.context } : undefined),
      ...(enableCitations ? { citations: { enabled: true } } : undefined)
    }
  }

  return yield* new AiError.AiError({
    module: "AnthropicLanguageModel",
    method: "prepareMessages",
    reason: new AiError.InvalidUserInputError({
      description: `Detected unsupported media type for file: '${part.mediaType}'`
    })
  })
})

const prepareTools = Effect.fnUntraced(
  function*<Tools extends ReadonlyArray<Tool.Any>>({ betas, capabilities, config, options, toolNameMapper }: {
    readonly betas: Set<string>
    readonly capabilities: ModelCapabilities
    readonly config: typeof Config.Service
    readonly options: LanguageModel.ProviderOptions
    readonly toolNameMapper: Tool.NameMapper<Tools>
  }): Effect.fn.Return<{
    readonly tools: ReadonlyArray<AnthropicUserDefinedTool | AnthropicProviderDefinedTool> | undefined
    readonly toolChoice: typeof Generated.BetaToolChoice.Encoded | undefined
  }, AiError.AiError> {
    // Return a JSON response tool when using non-native structured outputs
    if (options.responseFormat.type === "json" && !capabilities.supportsStructuredOutput) {
      const input_schema = yield* tryJsonSchema(options.responseFormat.schema, "prepareTools")
      const userDescription = SchemaAST.resolveDescription(options.responseFormat.schema.ast)
      const description = Predicate.isNotUndefined(userDescription) ? `${userDescription} - ` : ""
      return {
        tools: [{
          name: options.responseFormat.objectName,
          description: `${description}You MUST respond with a JSON object.`,
          input_schema: input_schema as any
        }],
        toolChoice: {
          type: "tool",
          name: options.responseFormat.objectName,
          disable_parallel_tool_use: true
        }
      }
    }

    if (options.tools.length === 0 || options.toolChoice === "none") {
      return { tools: undefined, toolChoice: undefined }
    }

    const userTools: Array<AnthropicUserDefinedTool> = []
    const providerTools: Array<AnthropicProviderDefinedTool> = []

    for (const tool of options.tools) {
      if (Tool.isUserDefined(tool) || Tool.isDynamic(tool)) {
        const description = Tool.getDescription(tool)
        const toolStrict = Tool.getStrictMode(tool)
        const strict = capabilities.supportsStructuredOutput
          ? (toolStrict ?? config.strictJsonSchema ?? true)
          : undefined
        const input_schema = yield* tryToolJsonSchema(tool, strict === true, "prepareTools")

        userTools.push({
          name: tool.name,
          input_schema: input_schema as any,
          ...(Predicate.isNotUndefined(description) ? { description } : undefined),
          ...(Predicate.isNotUndefined(strict) ? { strict } : undefined),
          ...(Context.get(tool.annotations, AnthropicTool.DeferLoading) ? { defer_loading: true } : undefined)
        })

        if (capabilities.supportsStructuredOutput === true) {
          betas.add("structured-outputs-2025-11-13")
        }
      }

      if (Tool.isProviderDefined(tool)) {
        const providerTool = tool as AnthropicTool.AnthropicTool
        switch (providerTool.id) {
          case "anthropic.bash_20241022": {
            betas.add("computer-use-2024-10-22")
            providerTools.push({ name: "bash", type: "bash_20241022" })
            break
          }

          case "anthropic.bash_20250124": {
            betas.add("computer-use-2025-01-24")
            providerTools.push({ name: "bash", type: "bash_20250124" })
            break
          }

          case "anthropic.code_execution_20250522": {
            betas.add("code-execution-2025-05-22")
            providerTools.push({ name: "code_execution", type: "code_execution_20250522" })
            break
          }

          case "anthropic.code_execution_20250825": {
            betas.add("code-execution-2025-08-25")
            providerTools.push({ name: "code_execution", type: "code_execution_20250825" })
            break
          }

          case "anthropic.computer_use_20241022": {
            betas.add("computer-use-2024-10-22")
            providerTools.push({
              name: "computer",
              type: "computer_20241022",
              display_height_px: providerTool.args.displayHeightPx,
              display_width_px: providerTool.args.displayWidthPx,
              display_number: providerTool.args.displayNumber ?? null
            })
            break
          }

          case "anthropic.computer_20250124": {
            betas.add("computer-use-2025-01-24")
            providerTools.push({
              name: "computer",
              type: "computer_20250124",
              display_height_px: providerTool.args.displayHeightPx,
              display_width_px: providerTool.args.displayWidthPx,
              display_number: providerTool.args.displayNumber ?? null
            })
            break
          }

          case "anthropic.computer_20251124": {
            betas.add("computer-use-2025-11-24")
            providerTools.push({
              name: "computer",
              type: "computer_20251124",
              display_height_px: providerTool.args.displayHeightPx,
              display_width_px: providerTool.args.displayWidthPx,
              display_number: providerTool.args.displayNumber ?? null,
              enable_zoom: providerTool.args.enableZoom ?? false
            })
            break
          }

          case "anthropic.memory_20250818": {
            betas.add("context-management-2025-06-27")
            providerTools.push({ name: "memory", type: "memory_20250818" })
            break
          }

          case "anthropic.text_editor_20241022": {
            betas.add("computer-use-2024-10-22")
            providerTools.push({ name: "str_replace_editor", type: "text_editor_20241022" })
            break
          }

          case "anthropic.text_editor_20250124": {
            betas.add("computer-use-2025-01-24")
            providerTools.push({ name: "str_replace_editor", type: "text_editor_20250124" })
            break
          }

          case "anthropic.text_editor_20250429": {
            betas.add("computer-use-2025-01-24")
            providerTools.push({ name: "str_replace_based_edit_tool", type: "text_editor_20250429" })
            break
          }

          case "anthropic.text_editor_20250728": {
            providerTools.push({
              name: "str_replace_based_edit_tool",
              type: "text_editor_20250728",
              max_characters: providerTool.args.max_characters ?? null
            })
            break
          }

          case "anthropic.tool_search_tool_bm25_20251119": {
            betas.add("advanced-tool-use-2025-11-20")
            providerTools.push({ name: "tool_search_tool_bm25", type: "tool_search_tool_bm25_20251119" })
            break
          }

          case "anthropic.tool_search_tool_regex_20251119": {
            providerTools.push({ name: "tool_search_tool_regex", type: "tool_search_tool_regex_20251119" })
            break
          }

          case "anthropic.web_search_20250305": {
            providerTools.push({
              name: "web_search",
              type: "web_search_20250305",
              max_uses: providerTool.args.maxUses ?? null,
              allowed_domains: providerTool.args.allowedDomains ?? null,
              blocked_domains: providerTool.args.blockedDomains ?? null,
              user_location: Predicate.isNotUndefined(providerTool.args.userLocation)
                ? {
                  type: providerTool.args.userLocation.type,
                  region: providerTool.args.userLocation.region ?? null,
                  city: providerTool.args.userLocation.city ?? null,
                  country: providerTool.args.userLocation.country ?? null,
                  timezone: providerTool.args.userLocation.timezone ?? null
                }
                : null
            })
            break
          }

          case "anthropic.web_fetch_20250910": {
            betas.add("web-fetch-2025-09-10")
            providerTools.push({
              name: "web_fetch",
              type: "web_fetch_20250910",
              max_uses: providerTool.args.maxUses ?? null,
              allowed_domains: providerTool.args.allowedDomains ?? null,
              blocked_domains: providerTool.args.blockedDomains ?? null,
              citations: providerTool.args.citations ?? null,
              max_content_tokens: providerTool.args.maxContentTokens ?? null
            })
            break
          }

          default: {
            return yield* AiError.make({
              module: "AnthropicLanguageModel",
              method: "prepareTools",
              reason: new AiError.InvalidUserInputError({
                description: `Received request to call unknown provider-defined tool '${tool.name}'`
              })
            })
          }
        }
      }
    }

    const tools = [...userTools, ...providerTools]
    let toolChoice: Mutable<typeof Generated.BetaToolChoice.Encoded> | undefined = undefined

    if (options.toolChoice === "auto") {
      toolChoice = { type: "auto" }
    } else if (options.toolChoice === "required") {
      toolChoice = { type: "any" }
    } else if ("tool" in options.toolChoice) {
      toolChoice = { type: "tool", name: toolNameMapper.getProviderName(options.toolChoice.tool) }
    } else {
      toolChoice = { type: options.toolChoice.mode === "required" ? "any" : "auto" }
    }

    if (
      Predicate.isNotUndefined(config.disableParallelToolCalls) &&
      Predicate.isNotUndefined(toolChoice) &&
      toolChoice.type !== "none"
    ) {
      toolChoice.disable_parallel_tool_use = config.disableParallelToolCalls
    }

    return {
      tools,
      toolChoice
    }
  }
)

// =============================================================================
// HTTP Details
// =============================================================================

const buildHttpResponseDetails = (
  response: HttpClientResponse.HttpClientResponse
): typeof Response.HttpResponseDetails.Type => ({
  status: response.status,
  headers: Redactable.redact(response.headers) as Record<string, string>
})

// =============================================================================
// Response Conversion
// =============================================================================

const makeResponse = Effect.fnUntraced(
  function*<Tools extends ReadonlyArray<Tool.Any>>({
    options,
    rawResponse,
    response,
    toolNameMapper
  }: {
    readonly options: LanguageModel.ProviderOptions
    readonly rawResponse: Generated.BetaMessage
    readonly response: HttpClientResponse.HttpClientResponse
    readonly toolNameMapper: Tool.NameMapper<Tools>
  }): Effect.fn.Return<
    Array<Response.PartEncoded>,
    AiError.AiError,
    IdGenerator.IdGenerator
  > {
    const parts: Array<Response.PartEncoded> = []
    const mcpToolCalls: Map<string, Response.ToolCallPartEncoded> = new Map()
    const serverToolCalls: Map<string, string> = new Map()
    const citableDocuments = extractCitableDocuments(options.prompt)
    const responseFormat = options.responseFormat
    const hasStructuredOutputTool = responseFormat.type === "json" &&
      rawResponse.content.some((part) => part.type === "tool_use" && part.name === responseFormat.objectName)

    parts.push({
      type: "response-metadata",
      id: rawResponse.id,
      modelId: rawResponse.model,
      timestamp: DateTime.formatIso(yield* DateTime.now)
    })

    for (const part of rawResponse.content) {
      switch (part.type) {
        case "fallback": {
          parts.push({
            type: "response-metadata",
            modelId: part.to.model,
            timestamp: DateTime.formatIso(yield* DateTime.now),
            metadata: { anthropic: { fallback: part } }
          })
          break
        }
        case "text": {
          // The response tool supplies the JSON payload. Accompanying prose
          // must not be concatenated with it during structured output decoding.
          if (hasStructuredOutputTool) {
            break
          }

          parts.push({
            type: "text",
            text: part.text
          })

          if (Predicate.isNotNullish(part.citations)) {
            for (const citation of part.citations) {
              const source = yield* processCitation(citation, citableDocuments)
              if (Predicate.isNotUndefined(source)) {
                parts.push(source)
              }
            }
          }

          break
        }

        case "thinking": {
          const metadata = {
            info: { type: "thinking", signature: part.signature }
          } as const

          parts.push({
            type: "reasoning",
            text: part.thinking,
            metadata: { anthropic: metadata }
          })
          break
        }

        case "redacted_thinking": {
          const metadata = {
            info: { type: "redacted_thinking", redactedData: part.data }
          } as const

          parts.push({
            type: "reasoning",
            text: "",
            metadata: { anthropic: metadata }
          })
          break
        }

        case "tool_use": {
          // When the `"json"` response format is requested, the JSON we need
          // is returned by a tool call injected into the request
          if (responseFormat.type === "json" && part.name === responseFormat.objectName) {
            parts.push({
              type: "text",
              text: JSON.stringify(part.input)
            })
          } else {
            // Extract caller info if present
            const caller = (part as any).caller
            const callerInfo = Predicate.isNotNullish(caller)
              ? {
                type: caller.type,
                toolId: "tool_id" in caller ? caller.tool_id : null
              }
              : undefined

            // Map the provider wire name (e.g. "memory") back to the tool's
            // custom name (e.g. "AnthropicMemory") that the toolkit is keyed by
            const toolName = toolNameMapper.getCustomName(part.name)
            const params = yield* transformToolCallParams(options, toolName, part.input)

            parts.push({
              type: "tool-call",
              id: part.id,
              name: toolName,
              params,
              ...(Predicate.isNotUndefined(callerInfo)
                ? { metadata: { anthropic: { caller: callerInfo } } }
                : undefined)
            })
          }

          break
        }

        case "server_tool_use": {
          const toolName = toolNameMapper.getCustomName(part.name)

          if (
            part.name === "bash_code_execution" ||
            part.name === "text_editor_code_execution"
          ) {
            parts.push({
              type: "tool-call",
              id: part.id,
              name: toolName,
              params: { type: part.name, ...part.input },
              providerExecuted: true
            })
          } else if (
            part.name === "code_execution" ||
            part.name === "web_fetch" ||
            part.name === "web_search"
          ) {
            const toolParams: Record<string, unknown> = { ...part.input }

            // Inject `type: "programmatic-tool-call"` when the input parameters
            // has the format `{ code: ... }`
            if (
              part.name === "code_execution" &&
              Predicate.hasProperty(part.input, "code") &&
              !Predicate.hasProperty(part.input, "type")
            ) {
              toolParams.type = "programmatic-tool-call"
            }

            parts.push({
              type: "tool-call",
              id: part.id,
              name: toolName,
              params: toolParams,
              providerExecuted: true
            })
          } else if (
            part.name === "tool_search_tool_bm25" ||
            part.name === "tool_search_tool_regex"
          ) {
            serverToolCalls.set(part.id, part.name)
            parts.push({
              type: "tool-call",
              id: part.id,
              name: toolName,
              params: part.input,
              providerExecuted: true
            })
          }

          break
        }

        case "mcp_tool_use": {
          const toolCall: Response.ToolCallPartEncoded = {
            type: "tool-call",
            id: part.id,
            name: part.name,
            params: part.input,
            providerExecuted: true,
            metadata: { anthropic: { mcp_tool: { server: part.server_name } } }
          }

          mcpToolCalls.set(part.id, toolCall)

          parts.push(toolCall)

          break
        }

        case "mcp_tool_result": {
          const toolCall = mcpToolCalls.get(part.tool_use_id)
          const mcpMetadata = toolCall?.metadata?.anthropic?.mcp_tool

          if (Predicate.isNotUndefined(toolCall)) {
            parts.push({
              type: "tool-result",
              id: part.tool_use_id,
              name: toolCall.name,
              isFailure: part.is_error,
              result: part.content,
              metadata: {
                anthropic: {
                  ...(Predicate.isNotNullish(mcpMetadata)
                    ? { mcp_tool: mcpMetadata } :
                    undefined)
                }
              }
            })
          }

          break
        }

        // Code Execution 20250522
        case "code_execution_tool_result": {
          const toolName = toolNameMapper.getCustomName("code_execution")