@harperfast/harper 5.0.30 → 5.1.0-beta.2

package/components/bedrock/index.ts

@@ -0,0 +1,823 @@
+/**
+ * AWS Bedrock backend (#633, Phase 6 of #510).
+ *
+ * Implements `ModelBackend` against AWS Bedrock via the official AWS SDK.
+ * Unlike Ollama / OpenAI / Anthropic, Bedrock requires SigV4-signed
+ * requests against region-specific endpoints; rolling that ourselves is
+ * not worth it. `@aws-sdk/client-bedrock-runtime` is declared as an
+ * **optional `peerDependency`** in Harper's `package.json`. Users who
+ * want the bedrock backend add the SDK to their own project's
+ * `package.json`; we dynamic-import on first use and throw a pointed
+ * error if it's missing.
+ *
+ * AWS credentials resolve via the SDK's standard chain (env / shared
+ * credentials file / EC2 / ECS / IAM roles for service accounts). No
+ * `apiKey` field on the Harper config — credential handling is the
+ * SDK's job, not ours.
+ *
+ * Bedrock has multiple model invocation shapes per family (Claude vs
+ * Llama vs Titan vs Cohere). The backend dispatches on the `model`
+ * field's prefix; per-family request/response translation lives in
+ * helpers below.
+ */
+import { setEmbedding, setGenerative } from '../../resources/models/backendRegistry.ts';
+import { assignFiniteTokenCount, composeSignal, requireModel } from '../../resources/models/backendHelpers.ts';
+import { ServerError } from '../../utility/errors/hdbError.ts';
+import harperLogger from '../../utility/logging/harper_logger.ts';
+import type {
+	BackendOpts,
+	EmbedOpts,
+	GenerateChunk,
+	GenerateInput,
+	GenerateOpts,
+	GenerateResult,
+	Message,
+	ModelBackend,
+	ModelCallResult,
+	ModelCapabilities,
+	ToolCall,
+	ToolDef,
+	TokenUsage,
+} from '../../resources/models/types.ts';
+
+// Defaults matching Anthropic's expectation when Claude is invoked via
+// Bedrock — Anthropic requires `max_tokens` on every request.
+const DEFAULT_MAX_TOKENS = 4096;
+// Max accumulated `bytes` from streamed Claude tool-use input_json_delta;
+// matches the cap in `components/anthropic/index.ts`.
+const MAX_TOOL_CALL_ARGS_CHARS = 1 << 20;
+
+const log = harperLogger.forComponent('bedrock').conditional;
+
+export type BedrockBackendKind = 'embedding' | 'generative';
+
+export interface BedrockBackendConfig {
+	/** AWS region (e.g. `us-east-1`). Required — Bedrock is regional. */
+	region?: string;
+	/**
+	 * Model ID per Bedrock conventions, e.g. `anthropic.claude-opus-4-v1:0`
+	 * for Claude, `meta.llama3-70b-instruct-v1:0` for Llama,
+	 * `amazon.titan-embed-text-v2:0` for Titan embed. The leading vendor
+	 * prefix is how the backend dispatches to the right per-family shape.
+	 */
+	model?: string;
+	requestTimeoutMs?: number;
+}
+
+/**
+ * SDK type-erased shape we use. We don't import `@aws-sdk/client-bedrock-runtime`
+ * at module init (it's an optional peerDep); types are kept loose so the
+ * compile doesn't depend on the SDK either.
+ */
+type SdkLike = {
+	BedrockRuntimeClient: new (config: { region?: string }) => {
+		send: (cmd: object) => Promise<unknown>;
+	};
+	InvokeModelCommand: new (input: { modelId: string; body: string; contentType?: string; accept?: string }) => object;
+	InvokeModelWithResponseStreamCommand: new (input: {
+		modelId: string;
+		body: string;
+		contentType?: string;
+		accept?: string;
+	}) => object;
+};
+
+let sdkPromise: Promise<SdkLike> | undefined;
+
+/**
+ * Load the AWS SDK on demand. Memoized — the SDK is module-scope state once
+ * loaded. Throws `BedrockBackendError` with a clear "add to your
+ * package.json" message if the SDK isn't installed.
+ */
+async function loadSdk(): Promise<SdkLike> {
+	if (!sdkPromise) {
+		sdkPromise = (async () => {
+			try {
+				// `@aws-sdk/client-bedrock-runtime` is declared as an optional
+				// peerDependency in Harper's `package.json` — it is not present
+				// in Harper's `node_modules` by design, so TypeScript can't
+				// resolve it at compile time. The runtime import resolves
+				// against the user's project tree.
+				// @ts-expect-error optional peerDependency, not resolvable at build time
+				const mod = (await import('@aws-sdk/client-bedrock-runtime')) as unknown as SdkLike;
+				return mod;
+			} catch (err) {
+				// Wipe the cached rejection so a follow-up install + retry works
+				// without restart. The thrown error is still propagated for this call.
+				sdkPromise = undefined;
+				throw new BedrockBackendError(
+					'@aws-sdk/client-bedrock-runtime is not installed. Add it to your project ' +
+						'(`npm install @aws-sdk/client-bedrock-runtime`) — Harper declares it as an optional peerDependency, ' +
+						'not a direct dependency, so applications that do not use the bedrock backend never pay the install cost. ' +
+						`Underlying error: ${(err as Error)?.message ?? err}`
+				);
+			}
+		})();
+	}
+	return sdkPromise;
+}
+
+/** Test-only hook to reset the memoized SDK promise between cases. */
+export function _resetSdkCacheForTests(): void {
+	sdkPromise = undefined;
+}
+
+/** Test-only hook to inject a fake SDK. */
+export function _injectSdkForTests(sdk: SdkLike): void {
+	sdkPromise = Promise.resolve(sdk);
+}
+
+/**
+ * `ModelBackend` for AWS Bedrock.
+ *
+ * - `embed` → `InvokeModel` against an embedding model (Titan, Cohere, etc.)
+ * - `generate` → `InvokeModel` against a generative model, per-family body shape
+ * - `generateStream` → `InvokeModelWithResponseStream`, per-family event parsing
+ *
+ * Tool support varies per model family — `capabilities()` advertises
+ * `tools: true` at the capability level; calls against models that don't
+ * support tools (or that haven't been wired into the per-family dispatcher
+ * yet) raise structured errors.
+ */
+export class BedrockBackend implements ModelBackend {
+	readonly name = 'bedrock';
+	readonly #region?: string;
+	readonly #defaultModel?: string;
+	readonly #requestTimeoutMs?: number;
+	#client?: { send: (cmd: object) => Promise<unknown> };
+
+	constructor(config: BedrockBackendConfig = {}) {
+		this.#region = config.region;
+		this.#defaultModel = config.model;
+		this.#requestTimeoutMs = config.requestTimeoutMs;
+	}
+
+	capabilities(): ModelCapabilities {
+		return { embed: true, generate: true, stream: true, tools: true, adapters: false };
+	}
+
+	async embed(input: string | string[], opts: BackendOpts<EmbedOpts>): Promise<ModelCallResult<Float32Array[]>> {
+		const model = opts.model ?? this.#defaultModel;
+		requireModel(model, 'embed', BedrockBackendError);
+		const family = familyOf(model);
+		const texts = Array.isArray(input) ? input : [input];
+
+		const client = await this.#getClient();
+		const sdk = await loadSdk();
+		const vectors: Float32Array[] = [];
+		let totalPromptTokens = 0;
+		let sawAnyTokens = false;
+
+		// Bedrock embedding APIs (Titan, Cohere) accept one text per call.
+		// Loop to honor the multi-input contract; concurrent dispatch would
+		// trip the SDK's request budget on larger batches without bounded
+		// concurrency, which is overkill for v1.
+		for (const text of texts) {
+			const body = buildEmbedBody(family, text, opts.inputType);
+			const command = new sdk.InvokeModelCommand({
+				modelId: model,
+				body: JSON.stringify(body),
+				contentType: 'application/json',
+				accept: 'application/json',
+			});
+			const response = (await this.#sendWithAbort(client, command, opts.signal)) as { body?: Uint8Array | string };
+			const parsed = parseInvokeModelResponse(response);
+			const { embedding, promptTokens } = extractEmbedResult(family, parsed);
+			vectors.push(Float32Array.from(embedding));
+			if (typeof promptTokens === 'number') {
+				totalPromptTokens += promptTokens;
+				sawAnyTokens = true;
+			}
+		}
+
+		const usage: TokenUsage = {};
+		if (sawAnyTokens) assignFiniteTokenCount(usage, 'embeddingTokens', totalPromptTokens);
+		return { status: 'completed', output: vectors, usage };
+	}
+
+	async generate(input: GenerateInput, opts: BackendOpts<GenerateOpts>): Promise<ModelCallResult<GenerateResult>> {
+		const model = opts.model ?? this.#defaultModel;
+		requireModel(model, 'generate', BedrockBackendError);
+		const family = familyOf(model);
+		const body = buildGenerateBody(family, input, opts);
+
+		const client = await this.#getClient();
+		const sdk = await loadSdk();
+		const command = new sdk.InvokeModelCommand({
+			modelId: model,
+			body: JSON.stringify(body),
+			contentType: 'application/json',
+			accept: 'application/json',
+		});
+		const response = (await this.#sendWithAbort(client, command, opts.signal)) as { body?: Uint8Array | string };
+		const parsed = parseInvokeModelResponse(response);
+		const result = extractGenerateResult(family, parsed);
+		return { status: 'completed', output: result.output, usage: result.usage };
+	}
+
+	async *generateStream(input: GenerateInput, opts: BackendOpts<GenerateOpts>): AsyncIterable<GenerateChunk> {
+		const model = opts.model ?? this.#defaultModel;
+		requireModel(model, 'generateStream', BedrockBackendError);
+		const family = familyOf(model);
+		const body = buildGenerateBody(family, input, opts);
+
+		const client = await this.#getClient();
+		const sdk = await loadSdk();
+		const command = new sdk.InvokeModelWithResponseStreamCommand({
+			modelId: model,
+			body: JSON.stringify(body),
+			contentType: 'application/json',
+			accept: 'application/json',
+		});
+		const response = (await this.#sendWithAbort(client, command, opts.signal)) as {
+			body?: AsyncIterable<{ chunk?: { bytes?: Uint8Array } }>;
+		};
+		if (!response.body) {
+			throw new BedrockBackendError(`Bedrock InvokeModelWithResponseStream returned no body for model ${model}`);
+		}
+
+		yield* parseStream(family, response.body);
+	}
+
+	async #getClient(): Promise<{ send: (cmd: object) => Promise<unknown> }> {
+		if (this.#client) return this.#client;
+		const sdk = await loadSdk();
+		this.#client = new sdk.BedrockRuntimeClient({ region: this.#region });
+		return this.#client;
+	}
+
+	/**
+	 * Send a command with caller-supplied AbortSignal + optional per-call
+	 * timeout composed via `AbortSignal.any`. The SDK accepts `abortSignal`
+	 * in the request options bag.
+	 */
+	async #sendWithAbort(
+		client: { send: (cmd: object, options?: { abortSignal?: AbortSignal }) => Promise<unknown> },
+		command: object,
+		callerSignal?: AbortSignal
+	): Promise<unknown> {
+		const abortSignal = composeSignal(callerSignal, this.#requestTimeoutMs);
+		return client.send(command, abortSignal ? { abortSignal } : undefined);
+	}
+}
+
+/**
+ * Boot-bridge helper. Called from `resources/models/bootstrap.ts` for each
+ * `models.embedding.<name>` / `models.generative.<name>` entry whose
+ * `backend: bedrock`. Construction is cheap (no SDK load) — the SDK loads
+ * lazily on first call.
+ */
+export function registerBedrockBackend(args: {
+	logicalName: string;
+	kind: BedrockBackendKind;
+	config: BedrockBackendConfig;
+}): void {
+	const backend = new BedrockBackend(args.config);
+	if (args.kind === 'embedding') setEmbedding(args.logicalName, backend);
+	else setGenerative(args.logicalName, backend);
+}
+
+export class BedrockBackendError extends ServerError {
+	constructor(message: string) {
+		super(message);
+		this.name = 'BedrockBackendError';
+	}
+}
+
+// ---------- per-family dispatch ----------
+
+type Family = 'anthropic' | 'amazon' | 'meta' | 'cohere' | 'mistral' | 'unknown';
+
+function familyOf(modelId: string): Family {
+	const prefix = modelId.split('.', 1)[0]?.toLowerCase() ?? '';
+	if (prefix === 'anthropic') return 'anthropic';
+	if (prefix === 'amazon') return 'amazon';
+	if (prefix === 'meta') return 'meta';
+	if (prefix === 'cohere') return 'cohere';
+	if (prefix === 'mistral') return 'mistral';
+	return 'unknown';
+}
+
+// ---------- embed body / result extraction ----------
+
+function buildEmbedBody(family: Family, text: string, inputType?: 'document' | 'query'): object {
+	if (family === 'amazon') {
+		// Titan embed v2: { inputText, dimensions?, normalize? }. Titan does
+		// not currently differentiate document vs query at the wire level.
+		return { inputText: text };
+	}
+	if (family === 'cohere') {
+		// Cohere embed-v3: `input_type` materially affects the produced vector
+		// — `search_document` and `search_query` produce different embeddings
+		// for the same text. Honor the caller's `inputType`; default to
+		// `search_document` when unset (matches Cohere's recommended default
+		// for indexing).
+		const cohereInputType = inputType === 'query' ? 'search_query' : 'search_document';
+		return { texts: [text], input_type: cohereInputType };
+	}
+	throw new BedrockBackendError(`Bedrock embed not supported for model family '${family}'`);
+}
+
+function extractEmbedResult(
+	family: Family,
+	parsed: Record<string, unknown>
+): { embedding: number[]; promptTokens?: number } {
+	if (family === 'amazon') {
+		const embedding = parsed.embedding;
+		if (!Array.isArray(embedding) || !embedding.every((n) => typeof n === 'number' && Number.isFinite(n))) {
+			throw new BedrockBackendError("Bedrock Titan response missing 'embedding' as a finite-number array");
+		}
+		const inputTextTokenCount = parsed.inputTextTokenCount;
+		return {
+			embedding: embedding as number[],
+			promptTokens: typeof inputTextTokenCount === 'number' ? inputTextTokenCount : undefined,
+		};
+	}
+	if (family === 'cohere') {
+		const embeddings = parsed.embeddings;
+		if (!Array.isArray(embeddings) || embeddings.length === 0) {
+			throw new BedrockBackendError("Bedrock Cohere response missing 'embeddings' array");
+		}
+		const first = embeddings[0];
+		if (!Array.isArray(first) || !first.every((n) => typeof n === 'number' && Number.isFinite(n))) {
+			throw new BedrockBackendError('Bedrock Cohere embedding vector is not an array of finite numbers');
+		}
+		return { embedding: first as number[] };
+	}
+	throw new BedrockBackendError(`Bedrock embed result extraction not implemented for family '${family}'`);
+}
+
+// ---------- generate body / result extraction ----------
+
+function buildGenerateBody(family: Family, input: GenerateInput, opts: BackendOpts<GenerateOpts>): object {
+	if (family === 'anthropic') return buildAnthropicBody(input, opts);
+	if (family === 'meta') return buildLlamaBody(input, opts);
+	if (family === 'amazon') return buildTitanGenerateBody(input, opts);
+	if (family === 'mistral') return buildMistralBody(input, opts);
+	if (family === 'cohere') return buildCohereGenerateBody(input, opts);
+	throw new BedrockBackendError(`Bedrock generate not supported for model family '${family}'`);
+}
+
+function extractGenerateResult(
+	family: Family,
+	parsed: Record<string, unknown>
+): { output: GenerateResult; usage: TokenUsage } {
+	if (family === 'anthropic') return extractAnthropicResult(parsed);
+	if (family === 'meta') return extractLlamaResult(parsed);
+	if (family === 'amazon') return extractTitanResult(parsed);
+	if (family === 'mistral') return extractMistralResult(parsed);
+	if (family === 'cohere') return extractCohereResult(parsed);
+	throw new BedrockBackendError(`Bedrock generate result extraction not implemented for family '${family}'`);
+}
+
+// Claude via Bedrock uses Anthropic's Messages API shape verbatim. Reuse the
+// translation patterns from `components/anthropic/index.ts` but keep the
+// code self-contained here — duplicated shape, different transport.
+function buildAnthropicBody(input: GenerateInput, opts: BackendOpts<GenerateOpts>): object {
+	const { messages, system } = normalizeMessages(input);
+	const tools = extractTools(input);
+	const body: Record<string, unknown> = {
+		anthropic_version: 'bedrock-2023-05-31',
+		messages: messages.map(toAnthropicMessage),
+		max_tokens: typeof opts.maxTokens === 'number' && opts.maxTokens > 0 ? opts.maxTokens : DEFAULT_MAX_TOKENS,
+	};
+	if (system) body.system = system;
+	if (tools && tools.length > 0) {
+		body.tools = tools.map((t) => ({ name: t.name, description: t.description, input_schema: t.parameters }));
+	}
+	if (typeof opts.temperature === 'number') body.temperature = opts.temperature;
+	return body;
+}
+
+function extractAnthropicResult(parsed: Record<string, unknown>): { output: GenerateResult; usage: TokenUsage } {
+	const content = Array.isArray(parsed.content) ? (parsed.content as AnthropicContentBlock[]) : [];
+	const text: string[] = [];
+	const toolCalls: ToolCall[] = [];
+	for (const block of content) {
+		if (block.type === 'text' && typeof block.text === 'string') text.push(block.text);
+		else if (block.type === 'tool_use' && block.id && block.name) {
+			const input = block.input && typeof block.input === 'object' ? block.input : {};
+			toolCalls.push({ id: block.id, name: block.name, arguments: input });
+		}
+	}
+	const usage: TokenUsage = {};
+	const usageObj = parsed.usage as { input_tokens?: unknown; output_tokens?: unknown } | undefined;
+	assignFiniteTokenCount(usage, 'promptTokens', usageObj?.input_tokens);
+	assignFiniteTokenCount(usage, 'completionTokens', usageObj?.output_tokens);
+	const output: GenerateResult = {
+		content: text.join(''),
+		finishReason: mapAnthropicStopReason(parsed.stop_reason as string | undefined),
+	};
+	if (toolCalls.length > 0) output.toolCalls = toolCalls;
+	return { output, usage };
+}
+
+function buildLlamaBody(input: GenerateInput, opts: BackendOpts<GenerateOpts>): object {
+	// Llama on Bedrock uses a flat `prompt` string. Caller's structured
+	// messages are flattened with role tags; not as expressive as native chat,
+	// but matches what AWS documents.
+	rejectToolsForFamily(input, 'meta');
+	const prompt = flattenToLlamaPrompt(input);
+	const body: Record<string, unknown> = { prompt };
+	if (typeof opts.maxTokens === 'number') body.max_gen_len = opts.maxTokens;
+	if (typeof opts.temperature === 'number') body.temperature = opts.temperature;
+	return body;
+}
+
+function extractLlamaResult(parsed: Record<string, unknown>): { output: GenerateResult; usage: TokenUsage } {
+	const generation = typeof parsed.generation === 'string' ? parsed.generation : '';
+	const usage: TokenUsage = {};
+	assignFiniteTokenCount(usage, 'promptTokens', parsed.prompt_token_count);
+	assignFiniteTokenCount(usage, 'completionTokens', parsed.generation_token_count);
+	const output: GenerateResult = {
+		content: generation,
+		finishReason: mapGenericStopReason(parsed.stop_reason as string | undefined),
+	};
+	return { output, usage };
+}
+
+function buildTitanGenerateBody(input: GenerateInput, opts: BackendOpts<GenerateOpts>): object {
+	rejectToolsForFamily(input, 'amazon');
+	const inputText = flattenToFlatPrompt(input);
+	const body: Record<string, unknown> = { inputText };
+	const textGenerationConfig: Record<string, unknown> = {};
+	if (typeof opts.maxTokens === 'number') textGenerationConfig.maxTokenCount = opts.maxTokens;
+	if (typeof opts.temperature === 'number') textGenerationConfig.temperature = opts.temperature;
+	if (Object.keys(textGenerationConfig).length > 0) body.textGenerationConfig = textGenerationConfig;
+	return body;
+}
+
+function extractTitanResult(parsed: Record<string, unknown>): { output: GenerateResult; usage: TokenUsage } {
+	const results = Array.isArray(parsed.results) ? parsed.results : [];
+	const first = (results[0] as Record<string, unknown>) ?? {};
+	const outputText = typeof first.outputText === 'string' ? first.outputText : '';
+	const usage: TokenUsage = {};
+	assignFiniteTokenCount(usage, 'promptTokens', parsed.inputTextTokenCount);
+	assignFiniteTokenCount(usage, 'completionTokens', first.tokenCount);
+	const output: GenerateResult = {
+		content: outputText,
+		finishReason: mapGenericStopReason(first.completionReason as string | undefined),
+	};
+	return { output, usage };
+}
+
+function buildMistralBody(input: GenerateInput, opts: BackendOpts<GenerateOpts>): object {
+	rejectToolsForFamily(input, 'mistral');
+	const prompt = flattenToFlatPrompt(input);
+	const body: Record<string, unknown> = { prompt };
+	if (typeof opts.maxTokens === 'number') body.max_tokens = opts.maxTokens;
+	if (typeof opts.temperature === 'number') body.temperature = opts.temperature;
+	return body;
+}
+
+function extractMistralResult(parsed: Record<string, unknown>): { output: GenerateResult; usage: TokenUsage } {
+	const outputs = Array.isArray(parsed.outputs) ? parsed.outputs : [];
+	const first = (outputs[0] as Record<string, unknown>) ?? {};
+	const text = typeof first.text === 'string' ? first.text : '';
+	const output: GenerateResult = {
+		content: text,
+		finishReason: mapGenericStopReason(first.stop_reason as string | undefined),
+	};
+	// Mistral via Bedrock doesn't currently return per-call token counts in a
+	// stable shape — leave usage empty.
+	return { output, usage: {} };
+}
+
+function buildCohereGenerateBody(input: GenerateInput, opts: BackendOpts<GenerateOpts>): object {
+	rejectToolsForFamily(input, 'cohere');
+	const prompt = flattenToFlatPrompt(input);
+	const body: Record<string, unknown> = { prompt };
+	if (typeof opts.maxTokens === 'number') body.max_tokens = opts.maxTokens;
+	if (typeof opts.temperature === 'number') body.temperature = opts.temperature;
+	return body;
+}
+
+function extractCohereResult(parsed: Record<string, unknown>): { output: GenerateResult; usage: TokenUsage } {
+	const generations = Array.isArray(parsed.generations) ? parsed.generations : [];
+	const first = (generations[0] as Record<string, unknown>) ?? {};
+	const text = typeof first.text === 'string' ? first.text : '';
+	const output: GenerateResult = {
+		content: text,
+		finishReason: mapGenericStopReason(first.finish_reason as string | undefined),
+	};
+	return { output, usage: {} };
+}
+
+// ---------- streaming dispatch ----------
+
+async function* parseStream(
+	family: Family,
+	body: AsyncIterable<{ chunk?: { bytes?: Uint8Array } }>
+): AsyncGenerator<GenerateChunk> {
+	if (family === 'anthropic') {
+		yield* parseAnthropicStream(body);
+		return;
+	}
+	if (family === 'meta' || family === 'amazon' || family === 'mistral' || family === 'cohere') {
+		yield* parseFlatStream(family, body);
+		return;
+	}
+	throw new BedrockBackendError(`Bedrock streaming not supported for model family '${family}'`);
+}
+
+async function* parseAnthropicStream(
+	body: AsyncIterable<{ chunk?: { bytes?: Uint8Array } }>
+): AsyncGenerator<GenerateChunk> {
+	const decoder = new TextDecoder('utf-8');
+	const toolBuf = new Map<number, { id: string; name: string; argumentsBuf: string }>();
+	let finalFinishReason: GenerateResult['finishReason'] | undefined;
+
+	for await (const event of body) {
+		if (!event.chunk?.bytes) continue;
+		const text = decoder.decode(event.chunk.bytes);
+		let parsed: Record<string, unknown>;
+		try {
+			parsed = JSON.parse(text) as Record<string, unknown>;
+		} catch {
+			throw new BedrockBackendError('Invalid JSON in Bedrock Anthropic stream chunk');
+		}
+		const chunk: GenerateChunk = {};
+		const type = parsed.type as string | undefined;
+		const index = parsed.index as number | undefined;
+		const contentBlock = parsed.content_block as AnthropicContentBlock | undefined;
+		const delta = parsed.delta as
+			| {
+					type?: string;
+					text?: string;
+					partial_json?: string;
+					stop_reason?: string | null;
+			  }
+			| undefined;
+
+		// Mid-stream upstream errors from Anthropic-via-Bedrock arrive as a
+		// `type: 'error'` chunk; without explicit handling the stream ends
+		// silently and the caller can't distinguish a clean end from an
+		// aborted one. Same posture as the direct Anthropic backend.
+		if (type === 'error') {
+			const upstream = (parsed as { error?: { message?: unknown } }).error?.message;
+			if (typeof upstream === 'string' && upstream.length > 0) {
+				const truncated = upstream.length > 500 ? upstream.slice(0, 500) + '…' : upstream;
+				throw new BedrockBackendError(`Bedrock Anthropic stream aborted by upstream error: ${truncated}`);
+			}
+			throw new BedrockBackendError('Bedrock Anthropic stream aborted by upstream error');
+		}
+
+		if (type === 'content_block_start' && index !== undefined && contentBlock?.type === 'tool_use') {
+			toolBuf.set(index, { id: contentBlock.id ?? '', name: contentBlock.name ?? '', argumentsBuf: '' });
+		}
+		if (type === 'content_block_delta' && index !== undefined && delta) {
+			if (delta.type === 'text_delta' && typeof delta.text === 'string' && delta.text.length > 0) {
+				chunk.deltaContent = delta.text;
+			} else if (delta.type === 'input_json_delta' && typeof delta.partial_json === 'string') {
+				const acc = toolBuf.get(index);
+				if (acc) {
+					if (acc.argumentsBuf.length + delta.partial_json.length > MAX_TOOL_CALL_ARGS_CHARS) {
+						throw new BedrockBackendError(
+							`Bedrock tool-call arguments exceed ${MAX_TOOL_CALL_ARGS_CHARS} chars (index ${index})`
+						);
+					}
+					acc.argumentsBuf += delta.partial_json;
+				}
+			}
+		}
+		if (type === 'content_block_stop' && index !== undefined) {
+			const acc = toolBuf.get(index);
+			if (acc?.id && acc.name) {
+				try {
+					const args = acc.argumentsBuf.length > 0 ? JSON.parse(acc.argumentsBuf) : {};
+					chunk.deltaToolCalls = [{ id: acc.id, name: acc.name, arguments: args }];
+				} catch {
+					log.warn?.(`Bedrock tool call dropped: malformed arguments (id=${acc.id}, name=${acc.name})`);
+				}
+				toolBuf.delete(index);
+			}
+		}
+		if (type === 'message_delta' && delta?.stop_reason) {
+			finalFinishReason = mapAnthropicStopReason(delta.stop_reason);
+			chunk.finishReason = finalFinishReason;
+		}
+		if (chunk.deltaContent || chunk.deltaToolCalls || chunk.finishReason) yield chunk;
+	}
+
+	if (!finalFinishReason && toolBuf.size > 0) {
+		const tail: Partial<ToolCall>[] = [];
+		for (const acc of toolBuf.values()) {
+			if (!acc.id || !acc.name) continue;
+			try {
+				const args = acc.argumentsBuf.length > 0 ? JSON.parse(acc.argumentsBuf) : {};
+				tail.push({ id: acc.id, name: acc.name, arguments: args });
+			} catch {
+				log.warn?.(`Bedrock tool call dropped on flush (id=${acc.id}, name=${acc.name})`);
+			}
+		}
+		toolBuf.clear();
+		if (tail.length > 0) yield { deltaToolCalls: tail };
+	}
+}
+
+async function* parseFlatStream(
+	family: Family,
+	body: AsyncIterable<{ chunk?: { bytes?: Uint8Array } }>
+): AsyncGenerator<GenerateChunk> {
+	// Llama / Titan / Mistral / Cohere via Bedrock all emit one JSON object
+	// per stream chunk with a family-specific "delta-content" field. We yield
+	// each as a GenerateChunk and rely on the final chunk's stop_reason
+	// (or family equivalent) to terminate.
+	const decoder = new TextDecoder('utf-8');
+	for await (const event of body) {
+		if (!event.chunk?.bytes) continue;
+		const text = decoder.decode(event.chunk.bytes);
+		let parsed: Record<string, unknown>;
+		try {
+			parsed = JSON.parse(text) as Record<string, unknown>;
+		} catch {
+			throw new BedrockBackendError('Invalid JSON in Bedrock stream chunk');
+		}
+		const chunk: GenerateChunk = {};
+		const deltaContent = extractFlatDeltaContent(family, parsed);
+		if (deltaContent && deltaContent.length > 0) chunk.deltaContent = deltaContent;
+		const stopReason = extractFlatStopReason(family, parsed);
+		if (stopReason) chunk.finishReason = mapGenericStopReason(stopReason);
+		if (chunk.deltaContent || chunk.finishReason) yield chunk;
+	}
+}
+
+function extractFlatDeltaContent(family: Family, parsed: Record<string, unknown>): string | undefined {
+	if (family === 'meta') return typeof parsed.generation === 'string' ? parsed.generation : undefined;
+	if (family === 'amazon') return typeof parsed.outputText === 'string' ? parsed.outputText : undefined;
+	if (family === 'mistral') {
+		const outputs = Array.isArray(parsed.outputs) ? parsed.outputs : [];
+		const first = (outputs[0] as Record<string, unknown>) ?? {};
+		return typeof first.text === 'string' ? first.text : undefined;
+	}
+	if (family === 'cohere') {
+		const generations = Array.isArray(parsed.generations) ? parsed.generations : [];
+		const first = (generations[0] as Record<string, unknown>) ?? {};
+		return typeof first.text === 'string' ? first.text : undefined;
+	}
+	return undefined;
+}
+
+function extractFlatStopReason(family: Family, parsed: Record<string, unknown>): string | undefined {
+	if (family === 'meta') return parsed.stop_reason as string | undefined;
+	if (family === 'amazon') return parsed.completionReason as string | undefined;
+	if (family === 'mistral') {
+		const outputs = Array.isArray(parsed.outputs) ? parsed.outputs : [];
+		const first = (outputs[0] as Record<string, unknown>) ?? {};
+		return first.stop_reason as string | undefined;
+	}
+	if (family === 'cohere') {
+		const generations = Array.isArray(parsed.generations) ? parsed.generations : [];
+		const first = (generations[0] as Record<string, unknown>) ?? {};
+		return first.finish_reason as string | undefined;
+	}
+	return undefined;
+}
+
+// ---------- message translation (shared by Claude-on-Bedrock body) ----------
+
+interface AnthropicContentBlock {
+	type: 'text' | 'tool_use' | 'tool_result';
+	text?: string;
+	id?: string;
+	name?: string;
+	input?: object;
+	tool_use_id?: string;
+	content?: string | AnthropicContentBlock[];
+}
+
+interface AnthropicMessage {
+	role: 'user' | 'assistant';
+	content: string | AnthropicContentBlock[];
+}
+
+function normalizeMessages(input: GenerateInput): { messages: Message[]; system?: string } {
+	if (typeof input === 'string') return { messages: [{ role: 'user', content: input }] };
+	if (Array.isArray(input)) {
+		const system: string[] = [];
+		const rest: Message[] = [];
+		for (const m of input) {
+			if (m.role === 'system') system.push(m.content);
+			else rest.push(m);
+		}
+		return system.length > 0 ? { messages: rest, system: system.join('\n\n') } : { messages: rest };
+	}
+	const explicit = input.system;
+	const inlineSystems: string[] = [];
+	const rest: Message[] = [];
+	for (const m of input.messages) {
+		if (m.role === 'system') inlineSystems.push(m.content);
+		else rest.push(m);
+	}
+	const combined = [explicit, ...inlineSystems]
+		.filter((s): s is string => typeof s === 'string' && s.length > 0)
+		.join('\n\n');
+	return combined.length > 0 ? { messages: rest, system: combined } : { messages: rest };
+}
+
+function extractTools(input: GenerateInput): ToolDef[] | undefined {
+	if (typeof input === 'string' || Array.isArray(input)) return undefined;
+	return input.tools;
+}
+
+/**
+ * Throw if the caller supplied `tools` on a Bedrock model family that this
+ * backend doesn't route them to. `capabilities()` advertises `tools: true`
+ * at the backend level, but only Anthropic-via-Bedrock actually consumes
+ * them in this PR — other families' body builders would silently drop
+ * the tools, leaving the caller unable to distinguish "model chose not to
+ * call" from "model never saw the tool". Loud error makes the
+ * unsupported-family case unambiguous; capability negotiation should
+ * eventually become model-aware (follow-up).
+ */
+function rejectToolsForFamily(input: GenerateInput, family: Family): void {
+	const tools = extractTools(input);
+	if (tools && tools.length > 0) {
+		throw new BedrockBackendError(
+			`Bedrock tool calls are not supported for model family '${family}' (only 'anthropic' models route tools in this version)`
+		);
+	}
+}
+
+function toAnthropicMessage(m: Message): AnthropicMessage {
+	if (m.role !== 'user' && m.role !== 'assistant' && m.role !== 'tool') {
+		return { role: 'user', content: m.content };
+	}
+	if (m.role === 'tool') {
+		return {
+			role: 'user',
+			content: [{ type: 'tool_result', tool_use_id: m.toolCallId ?? '', content: m.content }],
+		};
+	}
+	if (m.role === 'assistant' && m.toolCalls && m.toolCalls.length > 0) {
+		const blocks: AnthropicContentBlock[] = [];
+		if (m.content) blocks.push({ type: 'text', text: m.content });
+		for (const tc of m.toolCalls) {
+			blocks.push({ type: 'tool_use', id: tc.id, name: tc.name, input: tc.arguments ?? {} });
+		}
+		return { role: 'assistant', content: blocks };
+	}
+	return { role: m.role, content: m.content };
+}
+
+function flattenToLlamaPrompt(input: GenerateInput): string {
+	if (typeof input === 'string') return input;
+	const messages = Array.isArray(input) ? input : input.messages;
+	const system = !Array.isArray(input) && typeof input.system === 'string' ? input.system : undefined;
+	const parts: string[] = [];
+	if (system) parts.push(`<|begin_of_text|><|start_header_id|>system<|end_header_id|>\n\n${system}<|eot_id|>`);
+	for (const m of messages) {
+		parts.push(`<|start_header_id|>${m.role}<|end_header_id|>\n\n${m.content}<|eot_id|>`);
+	}
+	parts.push('<|start_header_id|>assistant<|end_header_id|>\n\n');
+	return parts.join('');
+}
+
+function flattenToFlatPrompt(input: GenerateInput): string {
+	if (typeof input === 'string') return input;
+	const messages = Array.isArray(input) ? input : input.messages;
+	const system = !Array.isArray(input) && typeof input.system === 'string' ? input.system : undefined;
+	const parts: string[] = [];
+	if (system) parts.push(`System: ${system}`);
+	for (const m of messages) parts.push(`${m.role[0].toUpperCase()}${m.role.slice(1)}: ${m.content}`);
+	parts.push('Assistant:');
+	return parts.join('\n\n');
+}
+
+// ---------- finish-reason mapping ----------
+
+function mapAnthropicStopReason(reason: string | null | undefined): GenerateResult['finishReason'] {
+	switch (reason) {
+		case 'max_tokens':
+			return 'length';
+		case 'tool_use':
+			return 'tool_calls';
+		case 'end_turn':
+		case 'stop_sequence':
+		default:
+			return 'stop';
+	}
+}
+
+function mapGenericStopReason(reason: string | null | undefined): GenerateResult['finishReason'] {
+	const r = (reason ?? '').toLowerCase();
+	if (r === 'length' || r === 'max_tokens' || r === 'max_token' || r === 'truncated') return 'length';
+	if (r === 'tool_calls' || r === 'tool_use' || r === 'function_call') return 'tool_calls';
+	if (r === 'content_filter' || r === 'content_filtered') return 'content_filter';
+	return 'stop';
+}
+
+// ---------- response parsing ----------
+
+function parseInvokeModelResponse(response: { body?: Uint8Array | string }): Record<string, unknown> {
+	if (!response.body) {
+		throw new BedrockBackendError('Bedrock InvokeModel response missing body');
+	}
+	const text =
+		typeof response.body === 'string' ? response.body : new TextDecoder('utf-8').decode(response.body as Uint8Array);
+	try {
+		return JSON.parse(text) as Record<string, unknown>;
+	} catch {
+		throw new BedrockBackendError('Bedrock InvokeModel response body is not valid JSON');
+	}
+}