@namzu/bedrock 4.0.1 → 5.0.1

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())
 		}
 	}
 }

package/src/health.ts

@@ -0,0 +1,194 @@
+/**
+ * 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 type { DoctorCheckResult } from '@namzu/sdk'
+import { providerVendorError } from '@namzu/sdk'
+
+/**
+ * Why the probe reached the verdict it did.
+ *
+ * Named for what an operator would do next, which is why `credentials` and
+ * `unreachable-model` are separate from `refused`: the first is a key to
+ * rotate, the second an id to change, the third a request the service looked
+ * at and would not take.
+ */
+export type BedrockHealthReason =
+	/** The model answered. */
+	| 'ok'
+	/** Nothing was probed: no model id was given and this driver holds none. */
+	| 'no-model'
+	/** The driver's own reachability rule refuses this id; nothing was sent. */
+	| 'unreachable-model'
+	/** No AWS credentials could be resolved on this machine. Never left it. */
+	| 'no-credentials'
+	/** AWS answered and rejected the credential or its permissions. */
+	| 'credentials'
+	/** The id is well-formed but this region serves no such model. */
+	| 'unknown-model'
+	/** The service looked at the request and refused it. */
+	| 'refused'
+	/** Reached, authenticated, and rate limited. The probe did not complete. */
+	| 'throttled'
+	/** The service answered and could not serve the request. */
+	| 'service'
+	/** Nothing was learned: the request did not get an answer. */
+	| 'unreachable-service'
+
+/**
+ * A `DoctorCheckResult` with the reason kept.
+ *
+ * Extends rather than replaces so it satisfies `LLMProvider.doctorCheck`
+ * unchanged: `runDoctor()` reads `status` and never sees the extra field, and a
+ * caller holding the concrete driver reads `reason` without a cast.
+ */
+export interface BedrockHealthReport extends DoctorCheckResult {
+	readonly reason: BedrockHealthReason
+	/** The id that was probed. Absent only when nothing was probed. */
+	readonly model?: string
+}
+
+/**
+ * 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: ReadonlyArray<readonly [RegExp, BedrockHealthReason]> = [
+	// 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: Readonly<Record<BedrockHealthReason, DoctorCheckResult['status']>> = {
+	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: Readonly<Partial<Record<BedrockHealthReason, string>>> = {
+	'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: unknown): BedrockHealthReason {
+	// 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 as { name?: unknown } | null)?.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: unknown,
+	model: string,
+	durationMs: number,
+): BedrockHealthReport {
+	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: BedrockHealthReason,
+	message: string,
+	extra: { readonly model?: string; readonly durationMs?: number } = {},
+): BedrockHealthReport {
+	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 } : {}),
+	}
+}

package/src/index.ts

@@ -23,4 +23,5 @@ export 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'