@wmaurer/effect-ai-amazon-bedrock 0.3.0 → 0.4.1

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
@@ -32,6 +36,7 @@ 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 { addGenAIAnnotations } from "effect/ai/Telemetry"
 import * as Tool from "effect/ai/Tool"
 import * as Context from "effect/Context"
 import * as DateTime from "effect/DateTime"
@@ -41,9 +46,10 @@ import { dual } from "effect/Function"
 import * as Layer from "effect/Layer"
 import * as Predicate from "effect/Predicate"
 import * as Result from "effect/Result"
-import type * as Schema from "effect/Schema"
+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 { AmazonBedrockClient } from "./AmazonBedrockClient.ts"
 import type {
@@ -54,17 +60,24 @@ import type {
   ConverseRequest,
   ConverseResponse,
   ConverseResponseStreamEvent,
+  ConverseStreamRequest,
   DocumentBlock,
   DocumentSource,
+  GuardrailConverseContentBlock,
+  GuardrailConverseContentQualifier,
+  GuardrailConverseImageBlock,
+  GuardrailStreamConfiguration,
   ImageBlock,
   MediaSource,
   Message,
   OutputConfig,
   SystemContentBlock,
+  TokenUsage,
   Tool as BedrockTool,
   ToolChoice,
   ToolConfiguration
 } from "./AmazonBedrockSchema.ts"
+import * as InternalGuardrails from "./internal/guardrails.ts"
 import * as InternalUtilities from "./internal/utilities.ts"
 
 /**
@@ -149,15 +162,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 +189,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 +269,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 +491,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 +684,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 +723,7 @@ export class Config extends Context.Service<
   Simplify<
     & Partial<
       Omit<
-        typeof ConverseRequest.Encoded,
+        typeof ConverseStreamRequest.Encoded,
         "messages" | "system" | "outputConfig"
       >
     >
@@ -635,7 +826,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> {
@@ -708,7 +899,7 @@ export const make = Effect.fnUntraced(function*({ config: providerConfig, model
         }
       }
 
-      const request: typeof ConverseRequest.Encoded = {
+      const request: typeof ConverseStreamRequest.Encoded = {
         ...config,
         modelId,
         system,
@@ -736,18 +927,35 @@ 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)
+      annotateRequest(options.span, request)
       const rawResponse = yield* client.converse({ payload: request })
+      // Before `makeResponse`, which fails a guardrail-blocked object with a
+      // `ContentPolicyError` after the call has already spent its tokens.
+      annotateResponse(options.span, request.modelId, rawResponse.stopReason, rawResponse.usage)
       return yield* makeResponse(request, rawResponse, options, nameMapper, documents)
     }),
     streamText: Effect.fnUntraced(function*(options) {
       const { documents, nameMapper, request } = yield* makeRequest(options)
+      annotateRequest(options.span, request)
       const stream = client.converseStream({ payload: request })
-      return yield* makeStreamResponse(request, stream, nameMapper, documents)
+      return yield* makeStreamResponse(request, stream, options.tools, nameMapper, documents, options.span)
     }, (effect, _options) => effect.pipe(Stream.unwrap))
   })
 })
 
+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.
  *
@@ -818,18 +1026,40 @@ const documentFormats: Record<string, typeof DocumentBlock.Encoded["format"]> =
 /** Matches any absolute url, so a non-s3 one is rejected instead of being treated as base64 data. */
 const urlPattern = /^[a-z][a-z0-9+.-]*:\/\//i
 
+/** Matches the header of a `data:` url, up to the comma before its payload. */
+const dataUrlPattern = /^data:[^,]*?(;base64)?,/i
+
 /**
  * Resolves file part data into a Converse media source.
  *
  * **Details**
  *
  * String data is already base64 per `Prompt.FilePart`, so it is passed through
- * untouched. The only remote source Converse accepts is an S3 location.
+ * untouched. A `data:` url has no `://`, so it is matched on its own, and only
+ * its base64 payload is sent. The only remote source Converse accepts is an S3
+ * location.
  */
 const fileSource: (
   data: typeof Prompt.FilePart.Type["data"]
 ) => Effect.Effect<typeof MediaSource.Encoded, AiError.AiError> = Effect.fnUntraced(function*(data) {
-  if (data instanceof URL || (typeof data === "string" && urlPattern.test(data))) {
+  if (data instanceof Uint8Array) {
+    return { bytes: Base64.encode(data) }
+  }
+  const string = data instanceof URL ? data.href : data
+  const dataUrl = dataUrlPattern.exec(string)
+  if (dataUrl !== null) {
+    if (Predicate.isUndefined(dataUrl[1])) {
+      return yield* AiError.make({
+        module: "AmazonBedrockLanguageModel",
+        method: "prepareMessages",
+        reason: new AiError.InvalidUserInputError({
+          description: `Unsupported file url '${dataUrl[0]}...' - a data url must have a base64 payload`
+        })
+      })
+    }
+    return { bytes: string.slice(dataUrl[0].length) }
+  }
+  if (data instanceof URL || urlPattern.test(data)) {
     const url = data instanceof URL ? data : new URL(data)
     if (url.protocol !== "s3:") {
       return yield* AiError.make({
@@ -842,7 +1072,7 @@ const fileSource: (
     }
     return { s3Location: { uri: url.toString() } }
   }
-  return { bytes: typeof data === "string" ? data : Base64.encode(data) }
+  return { bytes: data }
 })
 
 /**
@@ -871,7 +1101,7 @@ const documentSource: (
     if (data instanceof Uint8Array) {
       return { text: new TextDecoder().decode(data) }
     }
-    const decoded = Base64.decodeString(data as string)
+    const decoded = Base64.decodeString(source.bytes)
     if (Result.isFailure(decoded)) {
       return yield* AiError.make({
         module: "AmazonBedrockLanguageModel",
@@ -902,6 +1132,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>
@@ -933,7 +1202,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 })
@@ -950,9 +1219,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) } })
@@ -1048,6 +1322,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
@@ -1129,6 +1413,26 @@ const tryToolJsonSchema = (tool: Tool.Any, method: string) =>
     catch: (error) => unsupportedSchemaError(error, method)
   })
 
+// Bedrock is sent each tool's codec schema, which differs from the tool's own
+// schema wherever the codec rewrites a parameter. Params that follow the codec
+// are re-encoded with the tool's schema for the Toolkit to decode. Any others
+// are left as they are, so that the Toolkit reports the error.
+const decodeToolParams = (
+  tools: ReadonlyArray<Tool.Any>,
+  toolName: string,
+  params: unknown
+): Effect.Effect<unknown> => {
+  const tool = tools.find((tool) => tool.name === toolName)
+  if (Predicate.isUndefined(tool)) {
+    return Effect.succeed(params)
+  }
+  return Effect.try(() => toCodecAnthropic(tool.parametersSchema).codec).pipe(
+    Effect.flatMap((codec) => Schema.decodeUnknownEffect(codec)(params)),
+    Effect.flatMap((decoded) => Schema.encodeUnknownEffect(tool.parametersSchema)(decoded)),
+    Effect.orElseSucceed(() => params)
+  ) as Effect.Effect<unknown>
+}
+
 interface ModelCapabilities {
   readonly supportsStructuredOutput: boolean
   readonly supportsForcedToolChoice: boolean
@@ -1326,7 +1630,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
@@ -1380,11 +1684,12 @@ const makeResponse: (
         }
         continue
       }
+      const name = nameMapper.getCustomName(part.toolUse.name)
       parts.push({
         type: "tool-call",
         id: part.toolUse.toolUseId,
-        name: nameMapper.getCustomName(part.toolUse.name),
-        params: part.toolUse.input,
+        name,
+        params: yield* decodeToolParams(options.tools, name, part.toolUse.input),
         providerExecuted: false
       })
     } else if (Predicate.isNotUndefined(part.reasoningContent)) {
@@ -1434,6 +1739,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",
@@ -1453,23 +1774,26 @@ 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>,
+  tools: ReadonlyArray<Tool.Any>,
   nameMapper: Tool.NameMapper<ReadonlyArray<Tool.Any>>,
-  documents: ReadonlyArray<CitedDocument>
+  documents: ReadonlyArray<CitedDocument>,
+  span: Span
 ) => Effect.Effect<
   Stream.Stream<Response.StreamPartEncoded, AiError.AiError>,
   never,
   IdGenerator.IdGenerator
 > = Effect.fnUntraced(
-  function*(request, stream, nameMapper, documents) {
+  function*(request, stream, tools, nameMapper, documents, span) {
     // Acquired up front: the stream itself must not carry the requirement.
     const idGenerator = yield* IdGenerator.IdGenerator
 
@@ -1503,6 +1827,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) {
@@ -1671,7 +1996,7 @@ const makeStreamResponse: (
                 type: "tool-call",
                 id: block.id,
                 name: block.name,
-                params,
+                params: yield* decodeToolParams(tools, block.name, params),
                 providerExecuted: false
               })
             }
@@ -1682,6 +2007,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
           }
 
@@ -1692,6 +2018,7 @@ const makeStreamResponse: (
             if (Predicate.isNotUndefined(event.metadata.usage.cacheWriteInputTokens)) {
               usage.cacheWriteInputTokens = event.metadata.usage.cacheWriteInputTokens
             }
+            annotateResponse(span, request.modelId, stopReason, event.metadata.usage)
             // Terminal success event: usage is now populated — emit `finish`.
             parts.push({
               type: "finish",
@@ -1710,7 +2037,8 @@ const makeStreamResponse: (
                 }
               },
               // See `makeResponse`: the key is required (`Schema.UndefinedOr`).
-              response: undefined
+              response: undefined,
+              metadata: { amazonBedrock: InternalGuardrails.finishMetadata(stopReason, event.metadata.trace) }
             })
             break
           }
@@ -1748,6 +2076,41 @@ const makeStreamResponse: (
   }
 )
 
+// =============================================================================
+// Telemetry
+// =============================================================================
+
+const annotateRequest = (span: Span, request: typeof ConverseStreamRequest.Encoded): void => {
+  addGenAIAnnotations(span, {
+    provider: { name: "aws.bedrock" },
+    operation: { name: "chat" },
+    request: {
+      model: request.modelId,
+      maxTokens: request.inferenceConfig?.maxTokens,
+      temperature: request.inferenceConfig?.temperature,
+      topP: request.inferenceConfig?.topP,
+      stopSequences: request.inferenceConfig?.stopSequences
+    }
+  })
+}
+
+const annotateResponse = (span: Span, modelId: string, stopReason: string | null, usage: TokenUsage): void => {
+  const cacheRead = usage.cacheReadInputTokens ?? 0
+  const cacheWrite = usage.cacheWriteInputTokens ?? 0
+  addGenAIAnnotations(span, {
+    response: {
+      model: modelId,
+      finishReasons: stopReason === null ? undefined : [stopReason]
+    },
+    usage: {
+      inputTokens: usage.inputTokens + cacheRead + cacheWrite,
+      outputTokens: usage.outputTokens
+    }
+  })
+  span.attribute("gen_ai.usage.cache_read.input_tokens", cacheRead)
+  span.attribute("gen_ai.usage.cache_write.input_tokens", cacheWrite)
+}
+
 // =============================================================================
 // Utilities
 // =============================================================================