@wmaurer/effect-ai-amazon-bedrock 0.2.0 → 0.4.0

package/src/AmazonBedrockLanguageModel.ts

@@ -20,7 +20,11 @@
  * loudly with `AiError.InvalidUserInputError` rather than silently dropping
  * content. Prompt caching is opt-in per message or per part via provider
  * options. Citations are opt-in per document, and the citation blocks and
- * deltas Converse returns are surfaced as document source parts.
+ * deltas Converse returns are surfaced as document source parts. A guardrail
+ * applies through `Config.guardrailConfig`, and `guardContent` options on text
+ * parts, png and jpeg file parts, and system messages choose what it
+ * evaluates. Every finish part reports the raw stop reason and, when the trace
+ * is enabled, what the guardrail did.
  *
  * @stability unstable
  * @since 0.1.0
@@ -54,8 +58,13 @@ import type {
   ConverseRequest,
   ConverseResponse,
   ConverseResponseStreamEvent,
+  ConverseStreamRequest,
   DocumentBlock,
   DocumentSource,
+  GuardrailConverseContentBlock,
+  GuardrailConverseContentQualifier,
+  GuardrailConverseImageBlock,
+  GuardrailStreamConfiguration,
   ImageBlock,
   MediaSource,
   Message,
@@ -65,6 +74,7 @@ import type {
   ToolChoice,
   ToolConfiguration
 } from "./AmazonBedrockSchema.ts"
+import * as InternalGuardrails from "./internal/guardrails.ts"
 import * as InternalUtilities from "./internal/utilities.ts"
 
 /**
@@ -149,15 +159,6 @@ interface CachePointOptions {
 }
 
 declare module "effect/ai/Prompt" {
-  /**
-   * Amazon Bedrock options for system messages.
-   *
-   * @stability unstable
-   * @category models
-   * @since 0.1.0
-   */
-  export interface SystemMessageOptions extends CachePointOptions {}
-
   /**
    * Amazon Bedrock options for user messages.
    *
@@ -185,15 +186,6 @@ declare module "effect/ai/Prompt" {
    */
   export interface ToolMessageOptions extends CachePointOptions {}
 
-  /**
-   * Amazon Bedrock options for text prompt parts.
-   *
-   * @stability unstable
-   * @category models
-   * @since 0.1.0
-   */
-  export interface TextPartOptions extends CachePointOptions {}
-
   /**
    * Amazon Bedrock options for tool call prompt parts.
    *
@@ -274,6 +266,13 @@ interface FileOptions {
      * Converse cannot cite.
      */
     readonly citations?: Citations | null
+    /**
+     * Sends the image as a `guardContent` image block, for the guardrail to
+     * evaluate. Only an `image/png` or `image/jpeg` part whose data is bytes
+     * or base64 can be guarded. Any other file part with this option fails
+     * the request with `InvalidUserInputError`.
+     */
+    readonly guardContent?: true | null
   } | null
 }
 
@@ -489,6 +488,190 @@ const reasoningTextInfo = (signature: string | undefined): ReasoningInfo => ({
   signature: signature ?? null
 })
 
+/**
+ * A guardrail to apply to every request, set as `Config.guardrailConfig`.
+ *
+ * **Details**
+ *
+ * `generateText` and `generateObject` send it to Converse without
+ * `streamProcessingMode`, which Converse does not have. `streamText` sends it
+ * to ConverseStream as given.
+ *
+ * Without `guardContent` on any part, the guardrail evaluates every message
+ * and not the system prompt. Set `trace` to `"enabled"` to learn from the
+ * finish part whether the guardrail blocked or masked. The trace holds the
+ * matched text unmasked.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.4.0
+ */
+export type GuardrailConfig = typeof GuardrailStreamConfiguration.Encoded
+
+/**
+ * The role a guarded text part plays in a contextual grounding check.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.4.0
+ */
+export type GuardContentQualifier = typeof GuardrailConverseContentQualifier.Type
+
+/**
+ * Marks a text part or a system message for the guardrail to evaluate.
+ *
+ * **Details**
+ *
+ * `true` guards the text. `qualifiers` names its role in a contextual
+ * grounding check: the source documents are `grounding_source`, and the
+ * question is `query`. Once any part of a request is guarded, the guardrail
+ * evaluates only the guarded parts. The model still reads every part.
+ *
+ * The option stays on the part, so in a chat a guarded turn is evaluated
+ * again on every later turn.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.4.0
+ */
+export type GuardContent = true | {
+  readonly qualifiers: ReadonlyArray<GuardContentQualifier>
+}
+
+interface GuardableOptions {
+  readonly amazonBedrock?: {
+    /**
+     * Marks the end of the reusable prefix of the request. The cache point is
+     * emitted after the content this is attached to.
+     */
+    readonly cachePoint?: CachePoint | null
+    /**
+     * Sends the text as a `guardContent` block, for the guardrail to evaluate.
+     * Honoured on user text parts and system messages. On an assistant text
+     * part it fails the request with `InvalidUserInputError`.
+     */
+    readonly guardContent?: GuardContent | null
+  } | null
+}
+
+declare module "effect/ai/Prompt" {
+  /**
+   * Amazon Bedrock options for system messages.
+   *
+   * @stability unstable
+   * @category models
+   * @since 0.1.0
+   */
+  export interface SystemMessageOptions extends GuardableOptions {}
+
+  /**
+   * Amazon Bedrock options for text prompt parts.
+   *
+   * @stability unstable
+   * @category models
+   * @since 0.1.0
+   */
+  export interface TextPartOptions extends GuardableOptions {}
+}
+
+const textBlock = (
+  text: string,
+  options: GuardableOptions
+): { readonly text: string } | { readonly guardContent: typeof GuardrailConverseContentBlock.Encoded } => {
+  const guard = options.amazonBedrock?.guardContent
+  if (Predicate.isNullish(guard)) {
+    return { text }
+  }
+  return { guardContent: { text: guard === true ? { text } : { text, qualifiers: guard.qualifiers } } }
+}
+
+/**
+ * What a guardrail did to one side of the exchange.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.4.0
+ */
+export type GuardrailAction = "blocked" | "masked" | "none"
+
+/**
+ * What the guardrails did, read from the trace.
+ *
+ * **Details**
+ *
+ * `input` and `output` are the strongest action that any guardrail took on
+ * that side, `blocked` over `masked` over `none`, across every guardrail in
+ * the trace, enforced guardrails included. `policies` lists the trace keys of
+ * the policies that blocked or masked, such as `wordPolicy` or
+ * `sensitiveInformationPolicy`, each once, in the order the trace names them.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.4.0
+ */
+export type GuardrailOutcome = {
+  readonly input: GuardrailAction
+  readonly output: GuardrailAction
+  // Mutable, because the same type rides on ContentPolicyError, whose
+  // metadata must be MutableJson.
+  readonly policies: Array<string>
+}
+
+/**
+ * The Amazon Bedrock metadata on every finish part.
+ *
+ * **Details**
+ *
+ * `stopReason` is the raw Converse stop reason. It tells
+ * `guardrail_intervened` from `content_filtered`, which both finish with
+ * `"content-filter"`, and `max_tokens` from `model_context_window_exceeded`,
+ * which both finish with `"length"`. It is `null` only when a stream ended
+ * without a `messageStop` event.
+ *
+ * `guardrail` is `null` when the response carried no guardrail trace, which
+ * is the case unless `trace` is enabled in the guardrail config. A trace in
+ * which nothing acted gives `{ input: "none", output: "none", policies: [] }`.
+ * `trace` is the Converse trace as Bedrock sent it, or `null`. It holds the
+ * text that a policy matched, unmasked.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.4.0
+ */
+export type FinishMetadata = {
+  readonly stopReason: string | null
+  readonly guardrail: GuardrailOutcome | null
+  readonly trace: Schema.MutableJson | null
+}
+
+declare module "effect/ai/AiError" {
+  /**
+   * Amazon Bedrock metadata on the `ContentPolicyError` that `generateObject`
+   * fails with when a guardrail blocked the exchange. It is the metadata of
+   * the response's finish part.
+   *
+   * @stability unstable
+   * @category models
+   * @since 0.4.0
+   */
+  export interface ContentPolicyErrorMetadata extends ProviderMetadata {
+    readonly amazonBedrock?: FinishMetadata | null
+  }
+}
+
+declare module "effect/ai/Response" {
+  /**
+   * Amazon Bedrock metadata on the finish part.
+   *
+   * @stability unstable
+   * @category models
+   * @since 0.4.0
+   */
+  export interface FinishPartMetadata extends ProviderMetadata {
+    readonly amazonBedrock?: FinishMetadata | null
+  }
+}
+
 // =============================================================================
 // Configuration
 // =============================================================================
@@ -498,12 +681,17 @@ const reasoningTextInfo = (signature: string | undefined): ReasoningInfo => ({
  *
  * **Details**
  *
- * Derived from `ConverseRequest`, minus the fields built from the prompt, so
- * every Converse request parameter is settable per request. That includes
- * `additionalModelRequestFields`, which carries inference parameters specific
- * to the target model — among them extended thinking on Anthropic models. The
- * thinking budget is drawn from the same ceiling as the visible answer, so
- * `inferenceConfig.maxTokens` must exceed `budget_tokens`.
+ * Derived from `ConverseStreamRequest`, minus the fields built from the
+ * prompt, so every Converse request parameter is settable per request. That
+ * includes `additionalModelRequestFields`, which carries inference parameters
+ * specific to the target model — among them extended thinking on Anthropic
+ * models. The thinking budget is drawn from the same ceiling as the visible
+ * answer, so `inferenceConfig.maxTokens` must exceed `budget_tokens`.
+ *
+ * It also includes `guardrailConfig` (see {@link GuardrailConfig}). An
+ * override replaces the whole object, and `guardrailConfig: undefined` turns
+ * off a layer's guardrail for one request. `generateText` does not send
+ * `streamProcessingMode`.
  *
  * **Example** (Enabling extended thinking for one request)
  *
@@ -532,7 +720,7 @@ export class Config extends Context.Service<
   Simplify<
     & Partial<
       Omit<
-        typeof ConverseRequest.Encoded,
+        typeof ConverseStreamRequest.Encoded,
         "messages" | "system" | "outputConfig"
       >
     >
@@ -554,11 +742,15 @@ export class Config extends Context.Service<
        *
        * **Details**
        *
-       * Overrides automatic capability detection based on the model
-       * identifier. When `false`, `generateObject` asks for the object through
-       * a tool instead, which is forced on models that accept a forced
-       * `toolChoice` and left unforced, with an instruction to call it, on
-       * models that do not. Never sent to Bedrock.
+       * Overrides the default for the provider that the model identifier
+       * names. By default only Claude models, and ARNs that do not name their
+       * model, get native structured output. In probes on 2026-10-17 in
+       * eu-west-1 and us-east-1, Nova, Mistral Large 2402, Pixtral Large,
+       * Llama, and Palmyra answered `outputConfig` with a 400. When `false`,
+       * `generateObject` asks for the object through a tool instead, which is
+       * forced on models that accept a forced `toolChoice` and left unforced,
+       * with an instruction to call it, on models that do not. Never sent to
+       * Bedrock.
        *
        * When the prompt holds tool calls or tool results and the request
        * offers no tools, `generateObject` uses the tool even when this is
@@ -571,12 +763,19 @@ export class Config extends Context.Service<
        *
        * **Details**
        *
-       * Overrides automatic capability detection based on the model
-       * identifier. It decides whether the tool that `generateObject` uses
-       * without native structured output is forced, so with
-       * `structuredOutputs: false` it selects between the forced and the
-       * unforced tool, for example for an application inference profile ARN,
-       * which does not name its model. Never sent to Bedrock.
+       * Overrides the default for the provider that the model identifier
+       * names. It decides whether the tool that `generateObject` uses
+       * without native structured output is forced with `toolChoice`
+       * `{ any: {} }`, so with `structuredOutputs: false` it selects between
+       * the forced and the unforced tool, for example for an application
+       * inference profile ARN, which does not name its model. Never sent to
+       * Bedrock.
+       *
+       * By default Meta and Writer models, and Claude Opus 5.5, Sonnet 5.5,
+       * Fable 5.1, and Mythos 5.1, get the unforced tool. In probes on
+       * 2026-10-17 in us-east-1, Llama 3.1, 3.3, and 4 and Palmyra X4 and X5
+       * answered `any` with a 400, and in eu-west-1 Opus 5.5 and Sonnet 5.5
+       * rejected both `any` and a named `tool`.
        *
        * It steers only that tool. A `toolChoice` passed with the caller's own
        * tools, such as `"required"` or a named tool, goes to Bedrock
@@ -624,7 +823,7 @@ export const make = Effect.fnUntraced(function*({ config: providerConfig, model
     function*(
       options: LanguageModel.ProviderOptions
     ): Effect.fn.Return<{
-      readonly request: typeof ConverseRequest.Encoded
+      readonly request: typeof ConverseStreamRequest.Encoded
       readonly nameMapper: Tool.NameMapper<ReadonlyArray<Tool.Any>>
       readonly documents: ReadonlyArray<CitedDocument>
     }, AiError.AiError> {
@@ -674,9 +873,9 @@ export const make = Effect.fnUntraced(function*({ config: providerConfig, model
             }
           }
         } else {
-          // The object is asked for through a tool, which replaces the
-          // caller's tools. A model that rejects a forced `toolChoice` gets
-          // the tool unforced, and the request says to call it.
+          // The object tool is the only tool, so `any` forces it, and
+          // Mistral Large 2402 and Pixtral Large accept `any` but reject a
+          // named `tool`.
           const forced = forcedToolChoice ?? capabilities.supportsForcedToolChoice
           nameMapper = new Tool.NameMapper([])
           toolConfig = {
@@ -687,7 +886,7 @@ export const make = Effect.fnUntraced(function*({ config: providerConfig, model
                 inputSchema: { json: json as Record<string, unknown> }
               }
             }],
-            toolChoice: forced ? { tool: { name: responseFormat.objectName } } : { auto: {} }
+            toolChoice: forced ? { any: {} } : { auto: {} }
           }
           if (!forced) {
             system = [...(system ?? []), {
@@ -697,7 +896,7 @@ export const make = Effect.fnUntraced(function*({ config: providerConfig, model
         }
       }
 
-      const request: typeof ConverseRequest.Encoded = {
+      const request: typeof ConverseStreamRequest.Encoded = {
         ...config,
         modelId,
         system,
@@ -725,7 +924,8 @@ export const make = Effect.fnUntraced(function*({ config: providerConfig, model
   return yield* LanguageModel.make({
     codecTransformer: toCodecAnthropic,
     generateText: Effect.fnUntraced(function*(options) {
-      const { documents, nameMapper, request } = yield* makeRequest(options)
+      const { documents, nameMapper, request: streamRequest } = yield* makeRequest(options)
+      const request = toConverseRequest(streamRequest)
       const rawResponse = yield* client.converse({ payload: request })
       return yield* makeResponse(request, rawResponse, options, nameMapper, documents)
     }),
@@ -737,6 +937,17 @@ export const make = Effect.fnUntraced(function*({ config: providerConfig, model
   })
 })
 
+const toConverseRequest = (
+  request: typeof ConverseStreamRequest.Encoded
+): typeof ConverseRequest.Encoded => {
+  const { guardrailConfig, ...rest } = request
+  if (Predicate.isUndefined(guardrailConfig)) {
+    return rest
+  }
+  const { streamProcessingMode: _, ...converseGuardrail } = guardrailConfig
+  return { ...rest, guardrailConfig: converseGuardrail }
+}
+
 /**
  * Creates a layer for the Amazon Bedrock language model.
  *
@@ -891,6 +1102,45 @@ const documentName = (fileName: string | undefined, position: number): string =>
   return `document ${position}`
 }
 
+const guardedImageFormats: Record<string, typeof GuardrailConverseImageBlock.Encoded["format"]> = {
+  "image/jpeg": "jpeg",
+  "image/png": "png"
+}
+
+const guardedImage: (
+  part: Prompt.FilePart
+) => Effect.Effect<typeof GuardrailConverseImageBlock.Encoded, AiError.AiError> = Effect.fnUntraced(
+  function*(part) {
+    const format = guardedImageFormats[part.mediaType]
+    if (Predicate.isUndefined(format)) {
+      const reason = part.mediaType === "image/*"
+        ? "its format is unknown, and a guarded image must be image/png or image/jpeg"
+        : part.mediaType.startsWith("image/")
+        ? "a guarded image must be image/png or image/jpeg"
+        : "only text parts and png or jpeg images can be guarded"
+      return yield* AiError.make({
+        module: "AmazonBedrockLanguageModel",
+        method: "prepareMessages",
+        reason: new AiError.InvalidUserInputError({
+          description: `Unsupported guardContent on a file part of media type '${part.mediaType}' - ${reason}`
+        })
+      })
+    }
+    const source = yield* fileSource(part.data)
+    if (Predicate.isUndefined(source.bytes)) {
+      return yield* AiError.make({
+        module: "AmazonBedrockLanguageModel",
+        method: "prepareMessages",
+        reason: new AiError.InvalidUserInputError({
+          description: `Unsupported guardContent on an image at '${source.s3Location?.uri}' - a guarded image ` +
+            "must be sent as bytes or base64, not as an s3:// location"
+        })
+      })
+    }
+    return { format, source: { bytes: source.bytes } }
+  }
+)
+
 const prepareMessages: (options: LanguageModel.ProviderOptions) => Effect.Effect<{
   readonly system: ReadonlyArray<typeof SystemContentBlock.Encoded>
   readonly messages: ReadonlyArray<typeof Message.Encoded>
@@ -922,7 +1172,7 @@ const prepareMessages: (options: LanguageModel.ProviderOptions) => Effect.Effect
             })
           }
           for (const message of group.messages) {
-            system.push({ text: message.content })
+            system.push(textBlock(message.content, message.options))
             const cachePoint = getCachePoint(message)
             if (Predicate.isNotNull(cachePoint)) {
               system.push({ cachePoint })
@@ -939,9 +1189,14 @@ const prepareMessages: (options: LanguageModel.ProviderOptions) => Effect.Effect
               case "user": {
                 for (const part of message.content) {
                   if (part.type === "text") {
-                    content.push({ text: part.text })
+                    content.push(textBlock(part.text, part.options))
                     pushCachePoint(content, part)
                   } else if (part.type === "file") {
+                    if (part.options.amazonBedrock?.guardContent === true) {
+                      content.push({ guardContent: { image: yield* guardedImage(part) } })
+                      pushCachePoint(content, part)
+                      continue
+                    }
                     const imageFormat = imageFormats[part.mediaType]
                     if (Predicate.isNotUndefined(imageFormat)) {
                       content.push({ image: { format: imageFormat, source: yield* fileSource(part.data) } })
@@ -1037,6 +1292,16 @@ const prepareMessages: (options: LanguageModel.ProviderOptions) => Effect.Effect
               const isLastPart = k === message.content.length - 1
 
               if (part.type === "text") {
+                if (!Predicate.isNullish(part.options.amazonBedrock?.guardContent)) {
+                  return yield* AiError.make({
+                    module: "AmazonBedrockLanguageModel",
+                    method: "prepareMessages",
+                    reason: new AiError.InvalidUserInputError({
+                      description: "Unsupported guardContent on an assistant text part - this provider guards only " +
+                        "user text parts, user png and jpeg images, and system messages"
+                    })
+                  })
+                }
                 // Skip empty text blocks
                 if (part.text.trim().length === 0) {
                   continue
@@ -1124,16 +1389,36 @@ interface ModelCapabilities {
 }
 
 /**
- * Returns what a model accepts for structured output, optimistically assuming
- * modern capabilities for unknown IDs. Matched by substring, so foundation
- * model ids and inference profile ids (`eu.anthropic.…`) both resolve.
+ * Returns what a model accepts for structured output, looked up by the
+ * provider that the model ID names: `anthropic` in
+ * `eu.anthropic.claude-opus-4-8`, `amazon` in `amazon.nova-pro-v1:0`. A
+ * foundation model or inference profile ARN names its model at the end. Other
+ * ARNs, such as an application inference profile or a provisioned model, do
+ * not. They get the Claude rules, which give them the native structured output
+ * and forced tool of 0.2.0, on the unmeasured assumption that most of them
+ * wrap a Claude model.
+ *
+ * Probes on 2026-10-17, one run per model and call unless noted:
  *
+ * - Only Claude gets native structured output. Nova, Mistral Large 2402 and
+ *   Pixtral Large in eu-west-1, and Llama, Palmyra, DeepSeek R1, Mistral 7B
+ *   and Mixtral in us-east-1, answer `outputConfig` with a 400. gpt-oss-120b
+ *   accepts it but wrote text before the JSON in 3 of 4 runs.
+ * - The forced object tool, sent as `{ any: {} }`, returned the object on 15
+ *   of 16 models in eu-west-1, Claude Haiku 4.5 and Opus 4.8 included, and
+ *   on all 17 models in us-east-1 that accept a forced tool. Magistral Small
+ *   fails every object path.
+ * - Llama 3.1, 3.3 and 4 and Palmyra X4 and X5 (`meta`, `writer`) answer
+ *   `any` with a 400 in us-east-1, and so does each of them that the probe
+ *   sent a named `tool`, all but Llama 3.1 8B. They get the unforced tool. It
+ *   returned the object on Llama 3.1 8B, Llama 4 Scout and Maverick and
+ *   Palmyra X5, and a wrong object on Llama 3.1 70B and 3.3 70B.
  * - Claude models before Opus 4.1 / Sonnet 4.5 predate structured output, as
  *   in the Anthropic provider. This is not checked on Bedrock: a probe of 17
- *   Claude inference profiles in eu-west-1 on 2026-10-17 found Claude 3 Haiku,
- *   Claude 3 Sonnet and Sonnet 4 at end of life there, and did not try Claude
- *   3 Opus, 3.5 Haiku, 3.5 Sonnet, 3.7 Sonnet, Opus 4 or Opus 4.1.
- * - Every Claude profile that served the probe's requests (12 of 17)
+ *   Claude inference profiles in eu-west-1 found Claude 3 Haiku, Claude 3
+ *   Sonnet and Sonnet 4 at end of life there, and did not try Claude 3 Opus,
+ *   3.5 Haiku, 3.5 Sonnet, 3.7 Sonnet, Opus 4 or Opus 4.1.
+ * - Every Claude profile that served that probe's requests (12 of 17)
  *   accepted `outputConfig.textFormat`: Haiku 4.5 and 5.5, Opus 4.5 to 4.8, 5
  *   and 5.5, and Sonnet 4.5, 4.6, 5 and 5.5. Fable 5 and 5.1 rejected every
  *   request, with or without `textFormat`, with a data-retention
@@ -1146,23 +1431,51 @@ interface ModelCapabilities {
  * @see https://platform.claude.com/docs/en/build-with-claude/structured-outputs
  */
 const getModelCapabilities = (modelId: string): ModelCapabilities => {
-  const supportsForcedToolChoice = !(
-    modelId.includes("claude-opus-5-5") ||
-    modelId.includes("claude-sonnet-5-5") ||
-    modelId.includes("claude-fable-5-1") ||
-    modelId.includes("claude-mythos-5-1")
-  )
-  const supportsStructuredOutput = !(
-    modelId.includes("claude-sonnet-4-0") ||
-    modelId.includes("claude-sonnet-4-20250514") ||
-    modelId.includes("claude-3-7-sonnet") ||
-    modelId.includes("claude-opus-4-0") ||
-    modelId.includes("claude-opus-4-20250514") ||
-    modelId.includes("claude-3-")
-  )
-  return { supportsStructuredOutput, supportsForcedToolChoice }
+  const named = modelId.startsWith("arn:") ? namingArn.exec(modelId)?.[1] : modelId
+  if (Predicate.isUndefined(named)) {
+    return claudeCapabilities(modelId)
+  }
+  // `provider.model`, or `geo.provider.model` for an inference profile.
+  const [first = "", second = ""] = named.split(".")
+  const byProvider = capabilitiesByProvider.get(first) ?? capabilitiesByProvider.get(second)
+  return Predicate.isUndefined(byProvider) ? otherProvider : byProvider(named)
 }
 
+// Of the ARNs Converse accepts, only these two end in the ID of the model
+// they invoke.
+const namingArn = /^arn:[^:]+:bedrock:[^:]*:[^:]*:(?:foundation-model|inference-profile)\/(.+)$/
+
+const otherProvider: ModelCapabilities = { supportsStructuredOutput: false, supportsForcedToolChoice: true }
+
+const unforcedTool: ModelCapabilities = { supportsStructuredOutput: false, supportsForcedToolChoice: false }
+
+const claudeWithoutStructuredOutput = [
+  "claude-sonnet-4-0",
+  "claude-sonnet-4-20250514",
+  "claude-3-7-sonnet",
+  "claude-opus-4-0",
+  "claude-opus-4-20250514",
+  "claude-3-"
+]
+
+const claudeWithoutForcedToolChoice = [
+  "claude-opus-5-5",
+  "claude-sonnet-5-5",
+  "claude-fable-5-1",
+  "claude-mythos-5-1"
+]
+
+const claudeCapabilities = (modelId: string): ModelCapabilities => ({
+  supportsStructuredOutput: !claudeWithoutStructuredOutput.some((id) => modelId.includes(id)),
+  supportsForcedToolChoice: !claudeWithoutForcedToolChoice.some((id) => modelId.includes(id))
+})
+
+const capabilitiesByProvider = new Map<string, (modelId: string) => ModelCapabilities>([
+  ["anthropic", claudeCapabilities],
+  ["meta", () => unforcedTool],
+  ["writer", () => unforcedTool]
+])
+
 const tryJsonSchema = (schema: Schema.Top, method: string) =>
   Effect.try({
     try: () => Tool.getJsonSchemaFromSchema(schema, { transformer: toCodecAnthropic }),
@@ -1267,7 +1580,7 @@ const makeResponse: (
   documents: ReadonlyArray<CitedDocument>
 ) => Effect.Effect<
   Array<Response.PartEncoded>,
-  never,
+  AiError.AiError,
   IdGenerator.IdGenerator
 > = Effect.fnUntraced(function*(request, response, options, nameMapper, documents) {
   const idGenerator = yield* IdGenerator.IdGenerator
@@ -1375,6 +1688,22 @@ const makeResponse: (
     : InternalUtilities.resolveFinishReason(response.stopReason)
   const cacheReadTokens = response.usage.cacheReadInputTokens ?? 0
   const cacheWriteTokens = response.usage.cacheWriteInputTokens ?? 0
+  const metadata = InternalGuardrails.finishMetadata(response.stopReason, response.trace)
+
+  if (options.responseFormat.type === "json") {
+    const text = parts.flatMap((part) => part.type === "text" ? [part.text] : []).join("")
+    if (InternalGuardrails.blocksObject(response.stopReason, text)) {
+      return yield* AiError.make({
+        module: "AmazonBedrockLanguageModel",
+        method: "generateObject",
+        reason: new AiError.ContentPolicyError({
+          description: "An Amazon Bedrock guardrail intervened, and the response holds no JSON object. " +
+            `Bedrock answered: ${truncate(text, 200)}`,
+          metadata: { amazonBedrock: metadata }
+        })
+      })
+    }
+  }
 
   parts.push({
     type: "finish",
@@ -1394,14 +1723,15 @@ const makeResponse: (
     },
     // `Response.FinishPart` models `response` with `Schema.UndefinedOr`, which
     // requires the key; HTTP response details are not surfaced by the client.
-    response: undefined
+    response: undefined,
+    metadata: { amazonBedrock: metadata }
   })
 
   return parts
 })
 
 const makeStreamResponse: (
-  request: typeof ConverseRequest.Encoded,
+  request: typeof ConverseStreamRequest.Encoded,
   stream: Stream.Stream<ConverseResponseStreamEvent, AiError.AiError>,
   nameMapper: Tool.NameMapper<ReadonlyArray<Tool.Any>>,
   documents: ReadonlyArray<CitedDocument>
@@ -1444,6 +1774,7 @@ const makeStreamResponse: (
     // (which AWS sends AFTER messageStop and which carries the usage), so finish
     // reports the real token counts rather than the pre-metadata zeros.
     let finishReason: Response.FinishReason = "unknown"
+    let stopReason: string | null = null
 
     return stream.pipe(
       Stream.mapEffect(Effect.fnUntraced(function*(event) {
@@ -1591,6 +1922,19 @@ const makeStreamResponse: (
             const block = toolBlocks.get(index)
             if (Predicate.isNotUndefined(block)) {
               toolBlocks.delete(index)
+              const params = yield* Effect.try({
+                // A tool taking no arguments streams no deltas at all.
+                try: () => Tool.unsafeSecureJsonParse(block.params.length === 0 ? "{}" : block.params),
+                catch: () =>
+                  AiError.make({
+                    module: "AmazonBedrockLanguageModel",
+                    method: "makeStreamResponse",
+                    reason: new AiError.InvalidOutputError({
+                      description: `Bedrock streamed input for the \`${block.name}\` tool that is not valid JSON: ` +
+                        truncate(block.params, 500)
+                    })
+                  })
+              })
               parts.push({
                 type: "tool-params-end",
                 id: block.id
@@ -1599,8 +1943,7 @@ const makeStreamResponse: (
                 type: "tool-call",
                 id: block.id,
                 name: block.name,
-                // A tool taking no arguments streams no deltas at all.
-                params: Tool.unsafeSecureJsonParse(block.params.length === 0 ? "{}" : block.params),
+                params,
                 providerExecuted: false
               })
             }
@@ -1611,6 +1954,7 @@ const makeStreamResponse: (
             // Defer the `finish` part to the trailing `metadata` event (usage
             // is still zero here — metadata has not arrived yet).
             finishReason = InternalUtilities.resolveFinishReason(event.messageStop.stopReason)
+            stopReason = event.messageStop.stopReason
             break
           }
 
@@ -1639,7 +1983,8 @@ const makeStreamResponse: (
                 }
               },
               // See `makeResponse`: the key is required (`Schema.UndefinedOr`).
-              response: undefined
+              response: undefined,
+              metadata: { amazonBedrock: InternalGuardrails.finishMetadata(stopReason, event.metadata.trace) }
             })
             break
           }
@@ -1744,3 +2089,6 @@ const trimIfLast = (
   isLastPart: boolean,
   text: string
 ) => isLastGroup && isLastMessage && isLastPart ? text.trim() : text
+
+const truncate = (text: string, maxLength: number): string =>
+  text.length > maxLength ? `${text.slice(0, maxLength)}...` : text