@namzu/bedrock 4.0.1 → 5.0.0

package/dist/health.js

@@ -0,0 +1,131 @@
+/**
+ * What a health probe against this wire concluded, and why.
+ *
+ * `healthCheck` used to answer with one bit produced by `catch { return false }`.
+ * The three failures a caller actually needs apart — the credential is wrong,
+ * the service is down, that model is not invokable here — all arrived as
+ * `false`, and so did success, because the id it probed was one the driver's
+ * own `assertModelReachable` classifies as unreachable. A check that cannot
+ * pass is the same defect class as a check that cannot fail: neither carries
+ * information, and this one carried none in a shape that looked like an outage.
+ *
+ * So the reason is a value rather than a sentence. `status` is the
+ * `DoctorCheckResult` field `runDoctor()` reads; `reason` is what a caller
+ * switches on.
+ */
+import { providerVendorError } from '@namzu/sdk';
+/**
+ * AWS models its failures as distinct exception CLASSES rather than as status
+ * codes, and the class is the only thing that separates the cases an operator
+ * acts on differently.
+ *
+ * The SDK's `providerVendorError` deliberately flattens these into six kinds
+ * for the request path, where the question is "retry, compact, or give up".
+ * That is the right shape there and the wrong one here: it merges
+ * `ResourceNotFoundException` ("no such model in this region") with
+ * `ValidationException` ("the request was invalid") into `bad_request`, and
+ * those are the two answers a health check exists to tell apart. So the class
+ * is read here, where the raw error is still in hand.
+ *
+ * Matched on `name` rather than with `instanceof`: the exception classes are
+ * re-exported by every minor of the AWS SDK, and a caller running two copies of
+ * `@aws-sdk/client-bedrock-runtime` in one tree would fail every `instanceof`
+ * against errors that are otherwise correct.
+ */
+const REASON_BY_EXCEPTION = [
+    // Client-side, before a packet leaves: the credential chain found nothing.
+    // This is a definite answer about the machine, not a failure to reach AWS,
+    // and filing it as unreachable would tell someone with no credentials at
+    // all to go and check their network.
+    [/CredentialsProviderError|CredentialsError/i, 'no-credentials'],
+    [/AccessDenied|UnrecognizedClient|InvalidSignature|Unauthorized|Forbidden/i, 'credentials'],
+    [/ResourceNotFound/i, 'unknown-model'],
+    [/ThrottlingException|TooManyRequests|ServiceQuotaExceeded/i, 'throttled'],
+    [
+        /ServiceUnavailable|InternalServer|ModelNotReady|ModelTimeout|ModelStreamError|ModelError/i,
+        'service',
+    ],
+    [/Validation/i, 'refused'],
+];
+const STATUS_BY_REASON = {
+    ok: 'pass',
+    'no-model': 'skipped',
+    'unreachable-model': 'fail',
+    'no-credentials': 'fail',
+    credentials: 'fail',
+    'unknown-model': 'fail',
+    refused: 'fail',
+    // Reached, authenticated, throttled. The service is up, so this is not a
+    // failure of the integration — but the probe did not complete, so it is
+    // not a pass either, and reporting it as one would let a caller start
+    // sending traffic on the strength of a request that never ran.
+    throttled: 'warn',
+    service: 'fail',
+    // The check did not answer. Distinct from `fail` because nothing is known:
+    // telling an operator on broken wifi that Bedrock is down sends them to
+    // the wrong place.
+    'unreachable-service': 'inconclusive',
+};
+const REMEDIATION_BY_REASON = {
+    'no-credentials': 'Pass accessKeyId/secretAccessKey to the driver, or make the AWS default credential chain resolve here (env, shared config, SSO, or an instance role).',
+    credentials: 'Check the credential is current and that its IAM policy allows bedrock:InvokeModelWithResponseStream on this model in this region.',
+    'unknown-model': 'This region serves no model by that id. Enable model access in the target region, or use the inference-profile form (us./eu./apac./jp./global.) for a model served cross-region.',
+    refused: 'The service rejected the request itself. A model served only through an inference profile refuses the bare id — try the profile-prefixed form.',
+    throttled: 'Retry. The service is reachable and the credential authenticated.',
+    service: 'Nothing to do here; the service could not serve the request. Retry later.',
+    'unreachable-service': 'Nothing was learned about the service. Check network reachability of the Bedrock endpoint for this region before changing any credential.',
+};
+/** The reason an AWS failure implies; "nothing was learned" when unrecognised. */
+export function reasonForError(err) {
+    // Read off the object rather than gated on an instanceof check. Bedrock
+    // reports several failures as members of the stream's output union, and a
+    // deserialiser that hands one back as a plain shape would otherwise fall all
+    // the way through to "nothing was learned" while naming its own class.
+    const raw = err?.name;
+    const name = typeof raw === 'string' ? raw : '';
+    for (const [pattern, reason] of REASON_BY_EXCEPTION) {
+        if (pattern.test(name))
+            return reason;
+    }
+    // A region that was never configured also never leaves the machine, and the
+    // AWS SDK reports it as a plain `Error`, so there is no class to match.
+    const message = err instanceof Error ? err.message : String(err);
+    if (/region is missing|missing region/i.test(message))
+        return 'no-credentials';
+    return 'unreachable-service';
+}
+/**
+ * Build the report for a failure.
+ *
+ * The vendor error's message is taken from `providerVendorError` rather than
+ * from `err.message`, and that is not stylistic. AWS builds an exception
+ * message from the response body, so a credential the service echoed back is
+ * already inside `err.message` before this code sees it; `providerVendorError`
+ * is the one place in this estate that strips it. The class name is read off
+ * the raw error first — a name is not a body — and then the raw error is
+ * dropped.
+ */
+export function reportForError(err, model, durationMs) {
+    const reason = reasonForError(err);
+    const safe = providerVendorError({ providerId: 'bedrock', error: err });
+    return {
+        status: STATUS_BY_REASON[reason],
+        reason,
+        model,
+        message: safe.message,
+        ...(REMEDIATION_BY_REASON[reason] ? { remediation: REMEDIATION_BY_REASON[reason] } : {}),
+        durationMs,
+    };
+}
+/** The report for a reason that needs no vendor error to describe it. */
+export function report(reason, message, extra = {}) {
+    return {
+        status: STATUS_BY_REASON[reason],
+        reason,
+        message,
+        ...(extra.model !== undefined ? { model: extra.model } : {}),
+        ...(REMEDIATION_BY_REASON[reason] ? { remediation: REMEDIATION_BY_REASON[reason] } : {}),
+        ...(extra.durationMs !== undefined ? { durationMs: extra.durationMs } : {}),
+    };
+}
+//# sourceMappingURL=health.js.map

package/dist/health.js.map

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

package/dist/index.d.ts

@@ -15,5 +15,6 @@ declare module '@namzu/sdk' {
  */
 export declare function registerBedrock(options?: RegisterOptions): void;
 export { BEDROCK_CAPABILITIES, BedrockProvider } from './client.js';
+export type { BedrockHealthReason, BedrockHealthReport } from './health.js';
 export type { BedrockConfig, BedrockProviderConfig } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,YAAY,CAAA;AAEnE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAIvD,OAAO,QAAQ,YAAY,CAAC;IAC3B,UAAU,sBAAsB;QAC/B,OAAO,EAAE,qBAAqB,CAAA;KAC9B;CACD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAE/D;AAED,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AACnE,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,YAAY,CAAA;AAEnE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAIvD,OAAO,QAAQ,YAAY,CAAC;IAC3B,UAAU,sBAAsB;QAC/B,OAAO,EAAE,qBAAqB,CAAA;KAC9B;CACD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAE/D;AAED,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AACnE,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAC3E,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/bedrock",
-  "version": "4.0.1",
+  "version": "5.0.0",
   "description": "AWS Bedrock LLM provider for @namzu/sdk. Provides Converse API (chat + streaming) with full tool-use support.",
   "license": "FSL-1.1-MIT",
   "type": "module",
@@ -54,7 +54,7 @@
     "@types/node": "^22.19.17",
     "typescript": "^5.5.0",
     "vitest": "^3.2.6",
-    "@namzu/sdk": "^15.0.0"
+    "@namzu/sdk": "^26.0.0"
   },
   "scripts": {
     "build": "tsc --build",

package/src/client.ts

@@ -1,10 +1,7 @@
-import {
-	BedrockRuntimeClient,
-	ConverseCommand,
-	ConverseStreamCommand,
-} from '@aws-sdk/client-bedrock-runtime'
+import { BedrockRuntimeClient, ConverseStreamCommand } from '@aws-sdk/client-bedrock-runtime'
 import type {
 	Message as BedrockMessage,
+	CachePointBlock,
 	ContentBlock,
 	ConversationRole,
 	ConverseStreamCommandOutput,
@@ -32,13 +29,75 @@ import {
 	isProviderRequestError,
 	providerVendorError,
 } from '@namzu/sdk'
+import type { BedrockHealthReport } from './health.js'
+import { report, reportForError } from './health.js'
 import { assertModelReachable, isAnthropicServedModel } from './model-reachability.js'
 import type { BedrockConfig } from './types.js'
 
-function extractSystemBlocks(messages: ChatCompletionParams['messages']): SystemContentBlock[] {
-	return messages
-		.filter((m) => m.role === 'system')
-		.map((m) => ({ text: typeof m.content === 'string' ? m.content : '' }))
+/**
+ * The marker that asks this wire to cache everything before it.
+ *
+ * Caching is not a flag on the request here — it is a block spliced into
+ * the content, and a request without one is uncached however the caller
+ * configured it. That is why nothing was cached before: the driver read
+ * the cache counters faithfully and never emitted a marker, so the
+ * counters were honestly zero and a caller could not tell "caching does
+ * not help this workload" from "caching was never asked for".
+ *
+ * `default` is the only member of the wire's cache-point enum. `ttl` is
+ * deliberately not set: omitting it takes the service's own default,
+ * and an extended TTL is priced differently, so choosing one is a cost
+ * decision rather than a translation.
+ */
+const CACHE_POINT: { cachePoint: CachePointBlock } = { cachePoint: { type: 'default' } }
+
+/**
+ * System text, with a cache point after the last STATIC block.
+ *
+ * Position is the whole point, not presence. The runtime tags its static
+ * segment `'cache'` and its per-run dynamic segment `'ephemeral'`, and a
+ * marker appended at the end of the array would put the dynamic text
+ * inside the cached prefix — which changes every run, so every read would
+ * miss and every write would be paid for. A caller would see cache writes
+ * and no reads, which looks like a cold cache forever.
+ *
+ * No static block means no system breakpoint, rather than a breakpoint in
+ * an arbitrary place.
+ */
+function extractSystemBlocks(
+	messages: ChatCompletionParams['messages'],
+	cachingEnabled = false,
+): SystemContentBlock[] {
+	const blocks: SystemContentBlock[] = []
+	let lastStatic = -1
+
+	for (const m of messages) {
+		if (m.role !== 'system') continue
+		blocks.push({ text: typeof m.content === 'string' ? m.content : '' })
+		if (m.cacheHint === 'cache') lastStatic = blocks.length - 1
+	}
+
+	if (cachingEnabled && lastStatic >= 0) blocks.splice(lastStatic + 1, 0, CACHE_POINT)
+
+	return blocks
+}
+
+/**
+ * The final cache point: after the last content block of the last
+ * non-empty message.
+ *
+ * An iteration only appends messages, so caching the whole conversation
+ * prefix here is what makes the NEXT turn read its history at cache rates
+ * — which on a long run is the largest single cost lever available.
+ */
+function applyMessageCachePoint(messages: BedrockMessage[]): void {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const content = messages[i]?.content
+		if (content && content.length > 0) {
+			content.push(CACHE_POINT)
+			return
+		}
+	}
 }
 
 function toBedrockRole(role: string): ConversationRole {
@@ -138,7 +197,10 @@ function extractToolNamesFromHistory(messages: ChatCompletionParams['messages'])
 	return Array.from(names)
 }
 
-export function toBedrockToolConfig(params: ChatCompletionParams): ToolConfiguration | undefined {
+export function toBedrockToolConfig(
+	params: ChatCompletionParams,
+	cachingEnabled = false,
+): ToolConfiguration | undefined {
 	// 'none' means the model must not call a tool. This used to map to the
 	// wire's 'auto', which means it MAY — the opposite, and silent. No wire
 	// format lets a model call a tool it was never given, so send none.
@@ -168,6 +230,16 @@ export function toBedrockToolConfig(params: ChatCompletionParams): ToolConfigura
 				}) as Tool,
 		)
 
+		// After the schemas, so the tool block — the largest fixed prefix on
+		// a tool-using run, and the one that changes least — is cached.
+		//
+		// The reconstruction path below deliberately does not get one. Those
+		// are placeholder specs minted to keep the wire happy when history
+		// references a tool the caller no longer passes; their descriptions
+		// are the literal string `(completed)`, so caching them would pin a
+		// prefix that is not the caller's tool set.
+		if (cachingEnabled) tools.push(CACHE_POINT)
+
 		const toolChoice = formatToolChoice(params.toolChoice)
 		return { tools, toolChoice }
 	}
@@ -202,6 +274,25 @@ function formatToolChoice(tc?: ToolChoice) {
 	return { auto: {} }
 }
 
+/**
+ * The failure Bedrock reported as a stream EVENT rather than as a throw.
+ *
+ * Several post-handshake failures arrive as members of the output union, after
+ * a 200. Ignoring them makes a throttled or failed stream look like a clean
+ * EOF — which is why this is read on the request path, and why the health probe
+ * reads it through the same function rather than through a second copy that
+ * could drift from this one.
+ */
+export function streamFailureIn(event: ConverseStreamOutput): unknown {
+	return (
+		('internalServerException' in event ? event.internalServerException : undefined) ??
+		('modelStreamErrorException' in event ? event.modelStreamErrorException : undefined) ??
+		('validationException' in event ? event.validationException : undefined) ??
+		('throttlingException' in event ? event.throttlingException : undefined) ??
+		('serviceUnavailableException' in event ? event.serviceUnavailableException : undefined)
+	)
+}
+
 interface RawBedrockUsage {
 	inputTokens?: number
 	outputTokens?: number
@@ -298,9 +389,26 @@ export class BedrockProvider implements LLMProvider {
 		// reason and the fix, rather than as an opaque validation error from
 		// a service that was asked for something this wire does not carry.
 		assertModelReachable(params.model)
-		const system = extractSystemBlocks(params.messages)
+
+		// The runtime asks for caching on every iteration by setting
+		// `cacheControl`. Honouring it costs three cache points — tools tail,
+		// static-system tail, last message — and the prompt is assembled
+		// tools → system → messages, so each later point also covers every
+		// section before it.
+		//
+		// Gated on the model family for the reason `isAnthropicServedModel`
+		// already exists: Converse is a multi-vendor wire, and prompt caching
+		// is a property of the models on it rather than of the wire. The gate
+		// fails toward today's behaviour — a model outside it sends exactly
+		// the bytes it sends now, uncached — because the alternative failure
+		// is a rejected request, which costs a caller a working integration
+		// rather than a discount they never had.
+		const cachingEnabled = params.cacheControl !== undefined && isAnthropicServedModel(params.model)
+
+		const system = extractSystemBlocks(params.messages, cachingEnabled)
 		const messages = toBedrockMessages(params.messages)
-		const toolConfig = toBedrockToolConfig(params)
+		if (cachingEnabled) applyMessageCachePoint(messages)
+		const toolConfig = toBedrockToolConfig(params, cachingEnabled)
 
 		const inferenceConfig: Record<string, unknown> = {}
 		if (params.maxTokens !== undefined) inferenceConfig.maxTokens = params.maxTokens
@@ -355,12 +463,7 @@ export class BedrockProvider implements LLMProvider {
 				// Bedrock reports several post-handshake failures as UNION
 				// EVENTS, not thrown exceptions. Ignoring these members makes a
 				// throttled or failed stream look like a clean EOF.
-				const streamFailure =
-					('internalServerException' in event ? event.internalServerException : undefined) ??
-					('modelStreamErrorException' in event ? event.modelStreamErrorException : undefined) ??
-					('validationException' in event ? event.validationException : undefined) ??
-					('throttlingException' in event ? event.throttlingException : undefined) ??
-					('serviceUnavailableException' in event ? event.serviceUnavailableException : undefined)
+				const streamFailure = streamFailureIn(event)
 				if (streamFailure) {
 					throw providerVendorError({
 						providerId: 'bedrock',
@@ -459,10 +562,40 @@ export class BedrockProvider implements LLMProvider {
 		}
 	}
 
+	/**
+	 * The menu this driver offers.
+	 *
+	 * Every Claude id here is the `bedrock-runtime` Model ID from the vendor's
+	 * own model card, and that is a correction rather than a preference: the
+	 * two entries this list used to carry — `anthropic.claude-sonnet-4-20250514`
+	 * and `anthropic.claude-haiku-4-20250514` — are ids `assertModelReachable`
+	 * refuses, so an operator picking either off the menu got a throw before any
+	 * request was built. A catalogue its own request path rejects is worse than
+	 * a short one.
+	 *
+	 * The card for Claude Haiku 4.5 is what settles that the predicate is right
+	 * rather than too strict. It lists the SAME model under two ids on two
+	 * endpoints: `anthropic.claude-haiku-4-5-20251001-v1:0` on
+	 * `bedrock-runtime`, and the unversioned `anthropic.claude-haiku-4-5` on
+	 * `bedrock-mantle`, at a different URL. The bare form is a real id for the
+	 * endpoint this driver does not speak — which is exactly the claim
+	 * `model-reachability.ts` makes, stated by the vendor in one table.
+	 *
+	 * "Claude Haiku 4" was never a model. The Haiku line goes 3.5 to 4.5, and
+	 * the id that shipped here carried Sonnet 4's launch date.
+	 *
+	 * `inputPrice`/`outputPrice` are per million tokens and are DISPLAY data:
+	 * `resolveModelPricing` in `@namzu/sdk` has no `bedrock` vendor, so no run
+	 * is costed from them. The Haiku 4.5 rates are the reviewed ones from that
+	 * package's own `rates.source.json`. AWS publishes Bedrock's on-demand rates
+	 * on a page that renders them client-side, so they could not be read here,
+	 * and if Bedrock diverges from the vendor's list price this row is wrong in
+	 * that direction only.
+	 */
 	async listModels(): Promise<ModelInfo[]> {
 		return [
 			{
-				id: 'anthropic.claude-sonnet-4-20250514',
+				id: 'anthropic.claude-sonnet-4-20250514-v1:0',
 				name: 'Claude Sonnet 4 (Bedrock)',
 				contextWindow: 200_000,
 				maxOutputTokens: 64_000,
@@ -472,12 +605,12 @@ export class BedrockProvider implements LLMProvider {
 				supportsStreaming: true,
 			},
 			{
-				id: 'anthropic.claude-haiku-4-20250514',
-				name: 'Claude Haiku 4 (Bedrock)',
+				id: 'anthropic.claude-haiku-4-5-20251001-v1:0',
+				name: 'Claude Haiku 4.5 (Bedrock)',
 				contextWindow: 200_000,
 				maxOutputTokens: 64_000,
-				inputPrice: 0.8,
-				outputPrice: 4.0,
+				inputPrice: 1.0,
+				outputPrice: 5.0,
 				supportsToolUse: true,
 				supportsStreaming: true,
 			},
@@ -494,19 +627,92 @@ export class BedrockProvider implements LLMProvider {
 		]
 	}
 
-	async healthCheck(): Promise<boolean> {
+	/**
+	 * Can this driver serve `model` right now?
+	 *
+	 * One bit, and deliberately still one bit. Widening the return type would
+	 * break every caller that writes `if (await provider.healthCheck())`
+	 * SILENTLY — the code keeps compiling and starts always passing, because a
+	 * result object is truthy. {@link doctorCheck} is the same probe with its
+	 * reasoning intact, and is what to call when the answer matters.
+	 *
+	 * `model` is required in practice though the type says optional: this
+	 * driver's config holds no model, so with nothing passed there is nothing to
+	 * probe, and the answer is `false` for the stated reason `no-model` rather
+	 * than for a guessed one. It used to probe a hardcoded id instead, which is
+	 * how it came to send an id its own reachability rule rejects and report the
+	 * refusal as an outage.
+	 */
+	async healthCheck(model?: string): Promise<boolean> {
+		return (await this.doctorCheck(model)).status === 'pass'
+	}
+
+	/**
+	 * The health probe, with the reason it reached its verdict.
+	 *
+	 * Probes with `ConverseStream` rather than `Converse` because that is the
+	 * command {@link chatStream} sends. They are separate IAM actions —
+	 * `bedrock:InvokeModelWithResponseStream` and `bedrock:InvokeModel` — so a
+	 * probe on the other one can pass under a policy every real call fails
+	 * under, which is a green check about a request nobody makes.
+	 *
+	 * It costs one inference of one token. Nothing cheaper on the runtime client
+	 * establishes credentials, region and model reachability together, and the
+	 * alternatives establish them for a permission the request path does not
+	 * use.
+	 */
+	async doctorCheck(model?: string): Promise<BedrockHealthReport> {
+		if (model === undefined || model.trim() === '') {
+			return report(
+				'no-model',
+				'No model id was given and this driver holds none in its config, so nothing was probed. This is not a report that Bedrock is unhealthy.',
+			)
+		}
+
+		const startedAt = Date.now()
+		const elapsed = () => Date.now() - startedAt
+
+		// The same rule the request path applies, applied here. Skipping it is
+		// how the previous check came to send an id this driver classifies as
+		// uninvokable and then read the service's refusal as an outage.
 		try {
-			const command = new ConverseCommand({
-				modelId: 'anthropic.claude-haiku-4-20250514',
+			assertModelReachable(model)
+		} catch (err) {
+			return report('unreachable-model', err instanceof Error ? err.message : String(err), {
+				model,
+				durationMs: elapsed(),
+			})
+		}
+
+		try {
+			const command = new ConverseStreamCommand({
+				modelId: model,
 				messages: [{ role: 'user', content: [{ text: 'hi' }] }],
 				inferenceConfig: { maxTokens: 1 },
 			})
-			const response = await this.client.send(command, {
-				requestTimeout: 5000,
-			})
-			return response.$metadata.httpStatusCode === 200
-		} catch {
-			return false
+			const response = await this.client.send(command, { requestTimeout: 5000 })
+
+			// No branch on the status code: this SDK throws for a non-2xx, so a
+			// handshake that returns at all returned success. A branch production
+			// cannot enter is one only a fixture unlike production could test.
+			if (!response.stream) {
+				return report('service', 'bedrock accepted the request and returned no stream body', {
+					model,
+					durationMs: elapsed(),
+				})
+			}
+
+			// The handshake is a 200 even when the model then refuses, because
+			// Bedrock reports those failures as members of the output union.
+			// Reading only the status would call that a pass.
+			for await (const event of response.stream as AsyncIterable<ConverseStreamOutput>) {
+				const failure = streamFailureIn(event)
+				if (failure) return reportForError(failure, model, elapsed())
+			}
+
+			return report('ok', `bedrock served ${model}`, { model, durationMs: elapsed() })
+		} catch (err) {
+			return reportForError(err, model, elapsed())
 		}
 	}
 }