gsd-pi 2.74.0 → 2.75.0-dev.fd2382b9f

package/packages/pi-ai/src/models/index.ts

@@ -0,0 +1,106 @@
+import { MODELS } from "./generated/index.js";
+import { CUSTOM_MODELS } from "./custom.js";
+import { CAPABILITY_PATCHES, applyCapabilityPatches } from "./capability-patches.js";
+import type { Api, KnownProvider, Model, Usage } from "../types.js";
+
+const modelRegistry: Map<string, Map<string, Model<Api>>> = new Map();
+
+// Initialize registry from auto-generated MODELS (models.dev catalog)
+for (const [provider, models] of Object.entries(MODELS)) {
+	const providerModels = new Map<string, Model<Api>>();
+	for (const [id, model] of Object.entries(models)) {
+		providerModels.set(id, model as Model<Api>);
+	}
+	modelRegistry.set(provider, providerModels);
+}
+
+// Merge manually-maintained custom providers that are NOT in models.dev.
+// Custom models are additive — they never overwrite generated entries.
+// See: https://github.com/gsd-build/gsd-2/issues/2339
+for (const [provider, models] of Object.entries(CUSTOM_MODELS)) {
+	if (!modelRegistry.has(provider)) {
+		modelRegistry.set(provider, new Map<string, Model<Api>>());
+	}
+	const providerModels = modelRegistry.get(provider)!;
+	for (const [id, model] of Object.entries(models)) {
+		if (!providerModels.has(id)) {
+			providerModels.set(id, model as Model<Api>);
+		}
+	}
+}
+
+// Apply patches to the static registry at module load
+for (const [, providerModels] of modelRegistry) {
+	for (const [id, model] of providerModels) {
+		for (const patch of CAPABILITY_PATCHES) {
+			if (patch.match(model)) {
+				providerModels.set(id, {
+					...model,
+					capabilities: { ...patch.caps, ...model.capabilities },
+				});
+				break;
+			}
+		}
+	}
+}
+
+/** Providers that have entries in the generated MODELS constant */
+type GeneratedProvider = keyof typeof MODELS & KnownProvider;
+
+type ModelApi<
+	TProvider extends GeneratedProvider,
+	TModelId extends keyof (typeof MODELS)[TProvider],
+> = (typeof MODELS)[TProvider][TModelId] extends { api: infer TApi } ? (TApi extends Api ? TApi : never) : never;
+
+export function getModel<TProvider extends GeneratedProvider, TModelId extends keyof (typeof MODELS)[TProvider]>(
+	provider: TProvider,
+	modelId: TModelId,
+): Model<ModelApi<TProvider, TModelId>> {
+	const providerModels = modelRegistry.get(provider);
+	return providerModels?.get(modelId as string) as Model<ModelApi<TProvider, TModelId>>;
+}
+
+export function getProviders(): KnownProvider[] {
+	return Array.from(modelRegistry.keys()) as KnownProvider[];
+}
+
+export function getModels<TProvider extends KnownProvider>(
+	provider: TProvider,
+): Model<Api>[] {
+	const models = modelRegistry.get(provider);
+	return models ? (Array.from(models.values()) as Model<Api>[]) : [];
+}
+
+export function calculateCost<TApi extends Api>(model: Model<TApi>, usage: Usage): Usage["cost"] {
+	usage.cost.input = (model.cost.input / 1000000) * usage.input;
+	usage.cost.output = (model.cost.output / 1000000) * usage.output;
+	usage.cost.cacheRead = (model.cost.cacheRead / 1000000) * usage.cacheRead;
+	usage.cost.cacheWrite = (model.cost.cacheWrite / 1000000) * usage.cacheWrite;
+	usage.cost.total = usage.cost.input + usage.cost.output + usage.cost.cacheRead + usage.cost.cacheWrite;
+	return usage.cost;
+}
+
+/**
+ * Check if a model supports xhigh thinking level.
+ *
+ * Reads from `model.capabilities.supportsXhigh` — set via CAPABILITY_PATCHES
+ * for generated models or declared directly in custom model definitions.
+ * Do not add model-ID or provider-name checks here; update CAPABILITY_PATCHES instead.
+ */
+export function supportsXhigh<TApi extends Api>(model: Model<TApi>): boolean {
+	return model.capabilities?.supportsXhigh ?? false;
+}
+
+/**
+ * Check if two models are equal by comparing both their id and provider.
+ * Returns false if either model is null or undefined.
+ */
+export function modelsAreEqual<TApi extends Api>(
+	a: Model<TApi> | null | undefined,
+	b: Model<TApi> | null | undefined,
+): boolean {
+	if (!a || !b) return false;
+	return a.id === b.id && a.provider === b.provider;
+}
+
+export { MODELS, applyCapabilityPatches };

package/packages/pi-ai/src/models.generated.test.ts

@@ -1,7 +1,6 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { MODELS } from "./models.generated.js";
-import { getModel, getModels, getProviders } from "./models.js";
+import { MODELS, getModel, getModels, getProviders } from "./models/index.js";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Regression: qwen/qwen3.6-plus missing from OpenRouter (issue #3582)
@@ -327,6 +326,16 @@ describe("removed models are absent from the registry", () => {
 		{ provider: "openrouter", id: "meituan/longcat-flash-thinking" },
 		{ provider: "vercel-ai-gateway", id: "xai/grok-2-vision" },
 		{ provider: "anthropic", id: "claude-3-7-sonnet-latest" },
+		// Groq decommissioned models — issue #4257
+		{ provider: "groq", id: "llama3-70b-8192" },
+		{ provider: "groq", id: "llama3-8b-8192" },
+		{ provider: "groq", id: "deepseek-r1-distill-llama-70b" },
+		{ provider: "groq", id: "gemma2-9b-it" },
+		{ provider: "groq", id: "meta-llama/llama-4-maverick-17b-128e-instruct" },
+		{ provider: "groq", id: "mistral-saba-24b" },
+		{ provider: "groq", id: "moonshotai/kimi-k2-instruct" },
+		{ provider: "groq", id: "moonshotai/kimi-k2-instruct-0905" },
+		{ provider: "groq", id: "qwen-qwq-32b" },
 	];
 
 	for (const { provider, id } of removedModels) {
@@ -350,11 +359,18 @@ describe("spot-checks for models added in this regeneration", () => {
 		{ provider: "openrouter", id: "arcee-ai/trinity-large-thinking", reasoning: true },
 		{ provider: "openrouter", id: "openai/gpt-audio" },
 		{ provider: "openrouter", id: "anthropic/claude-opus-4.6-fast" },
+		{ provider: "openrouter", id: "anthropic/claude-opus-4.7" },
+		{ provider: "amazon-bedrock", id: "anthropic.claude-opus-4-7" },
+		{ provider: "amazon-bedrock", id: "us.anthropic.claude-opus-4-7" },
+		{ provider: "amazon-bedrock", id: "eu.anthropic.claude-opus-4-7" },
+		{ provider: "amazon-bedrock", id: "global.anthropic.claude-opus-4-7" },
+		{ provider: "google-antigravity", id: "claude-opus-4-7-thinking", reasoning: true },
 		{ provider: "openrouter", id: "qwen/qwen3.6-plus" },
 		{ provider: "groq", id: "groq/compound" },
 		{ provider: "groq", id: "groq/compound-mini" },
 		{ provider: "huggingface", id: "zai-org/GLM-5.1" },
 		{ provider: "openai", id: "gpt-5.3-chat-latest" },
+		{ provider: "openai-codex", id: "gpt-5.4-mini", reasoning: true },
 		{ provider: "mistral", id: "mistral-small-2603" },
 		{ provider: "zai", id: "glm-5.1" },
 	];

package/packages/pi-ai/src/models.test.ts

@@ -7,8 +7,8 @@ import type { Api, Model } from "./types.js";
 // Custom provider preservation (regression: #2339)
 //
 // Custom providers (like alibaba-coding-plan) are manually maintained and
-// NOT sourced from models.dev. They must survive models.generated.ts
-// regeneration by living in models.custom.ts.
+// NOT sourced from models.dev. They must survive generated catalog
+// regeneration by living in models/custom.ts.
 // ═══════════════════════════════════════════════════════════════════════════
 
 describe("model registry — custom providers", () => {
@@ -68,7 +68,7 @@ describe("model registry — custom providers", () => {
 	it("getModel retrieves alibaba-coding-plan models by provider+id", () => {
 		// Use type assertion to test runtime behavior — alibaba-coding-plan may come
 		// from custom models rather than the generated file, so the narrow
-		// GeneratedProvider type doesn't include it until models.custom.ts is merged.
+		// GeneratedProvider type doesn't include it until models/custom.ts is merged.
 		const model = getModel("alibaba-coding-plan" as any, "qwen3.5-plus" as any);
 		assert.ok(model, "Expected getModel to return a model for alibaba-coding-plan/qwen3.5-plus");
 		assert.equal(model.id, "qwen3.5-plus");
@@ -92,11 +92,12 @@ describe("model registry — custom zai provider (GLM-5.1)", () => {
 		assert.equal(model.api, "openai-completions");
 	});
 
-	it("glm-5.1 has reasoning enabled and correct context window", () => {
+	it("glm-5.1 has reasoning enabled and uses generated catalog precedence", () => {
 		const model = getModel("zai" as any, "glm-5.1" as any);
 		assert.ok(model);
 		assert.equal(model.reasoning, true);
-		assert.equal(model.contextWindow, 204800);
+		// Generated catalog entries are loaded first; custom models are additive-only.
+		assert.equal(model.contextWindow, 200000);
 		assert.equal(model.maxTokens, 131072);
 	});
 

package/packages/pi-ai/src/models.ts

@@ -1,153 +1,3 @@
-import { MODELS } from "./models.generated.js";
-import { CUSTOM_MODELS } from "./models.custom.js";
-import type { Api, KnownProvider, Model, ModelCapabilities, Usage } from "./types.js";
-
-const modelRegistry: Map<string, Map<string, Model<Api>>> = new Map();
-
-// Initialize registry from auto-generated MODELS (models.dev catalog)
-for (const [provider, models] of Object.entries(MODELS)) {
-	const providerModels = new Map<string, Model<Api>>();
-	for (const [id, model] of Object.entries(models)) {
-		providerModels.set(id, model as Model<Api>);
-	}
-	modelRegistry.set(provider, providerModels);
-}
-
-// Merge manually-maintained custom providers that are NOT in models.dev.
-// Custom models are additive — they never overwrite generated entries.
-// See: https://github.com/gsd-build/gsd-2/issues/2339
-for (const [provider, models] of Object.entries(CUSTOM_MODELS)) {
-	if (!modelRegistry.has(provider)) {
-		modelRegistry.set(provider, new Map<string, Model<Api>>());
-	}
-	const providerModels = modelRegistry.get(provider)!;
-	for (const [id, model] of Object.entries(models)) {
-		if (!providerModels.has(id)) {
-			providerModels.set(id, model as Model<Api>);
-		}
-	}
-}
-
-// ─── Capability Patches ───────────────────────────────────────────────────────
-//
-// Declare capabilities for models that pre-date the `capabilities` field or
-// that live in the auto-generated catalog (models.generated.ts) which we
-// cannot edit directly. Pattern-matching on model IDs is acceptable HERE
-// because this is the single source of truth — call sites must never repeat it.
-//
-// Add new entries as additional capabilities emerge. Existing models that
-// define `capabilities` in their model definition take precedence (the patch
-// only fills in fields that are not already set).
-
-type CapabilityPatch = { match: (m: Model<Api>) => boolean; caps: ModelCapabilities };
-
-const CAPABILITY_PATCHES: CapabilityPatch[] = [
-	// GPT-5.x supports xhigh thinking and OpenAI service tiers
-	{
-		match: (m) => m.id.includes("gpt-5.2") || m.id.includes("gpt-5.3") || m.id.includes("gpt-5.4"),
-		caps: { supportsXhigh: true, supportsServiceTier: true },
-	},
-	// Anthropic Opus 4.6 supports xhigh thinking
-	{
-		match: (m) => m.api === "anthropic-messages" && (m.id.includes("opus-4-6") || m.id.includes("opus-4.6")),
-		caps: { supportsXhigh: true },
-	},
-];
-
-/**
- * Apply capability patches to a list of models.
- *
- * Models constructed outside the static pi-ai registry (custom models from
- * models.json, extension-registered models, discovered models) do not pass
- * through the module-init patch loop. Call this function after assembling
- * any model list to ensure capabilities are set correctly.
- *
- * Explicit `capabilities` already set on a model take precedence over patches.
- */
-export function applyCapabilityPatches(models: Model<Api>[]): Model<Api>[] {
-	return models.map((model) => {
-		for (const patch of CAPABILITY_PATCHES) {
-			if (patch.match(model)) {
-				return {
-					...model,
-					capabilities: { ...patch.caps, ...model.capabilities },
-				};
-			}
-		}
-		return model;
-	});
-}
-
-// Apply patches to the static registry at module load
-for (const [, providerModels] of modelRegistry) {
-	for (const [id, model] of providerModels) {
-		for (const patch of CAPABILITY_PATCHES) {
-			if (patch.match(model)) {
-				providerModels.set(id, {
-					...model,
-					capabilities: { ...patch.caps, ...model.capabilities },
-				});
-				break;
-			}
-		}
-	}
-}
-
-/** Providers that have entries in the generated MODELS constant */
-type GeneratedProvider = keyof typeof MODELS & KnownProvider;
-
-type ModelApi<
-	TProvider extends GeneratedProvider,
-	TModelId extends keyof (typeof MODELS)[TProvider],
-> = (typeof MODELS)[TProvider][TModelId] extends { api: infer TApi } ? (TApi extends Api ? TApi : never) : never;
-
-export function getModel<TProvider extends GeneratedProvider, TModelId extends keyof (typeof MODELS)[TProvider]>(
-	provider: TProvider,
-	modelId: TModelId,
-): Model<ModelApi<TProvider, TModelId>> {
-	const providerModels = modelRegistry.get(provider);
-	return providerModels?.get(modelId as string) as Model<ModelApi<TProvider, TModelId>>;
-}
-
-export function getProviders(): KnownProvider[] {
-	return Array.from(modelRegistry.keys()) as KnownProvider[];
-}
-
-export function getModels<TProvider extends KnownProvider>(
-	provider: TProvider,
-): Model<Api>[] {
-	const models = modelRegistry.get(provider);
-	return models ? (Array.from(models.values()) as Model<Api>[]) : [];
-}
-
-export function calculateCost<TApi extends Api>(model: Model<TApi>, usage: Usage): Usage["cost"] {
-	usage.cost.input = (model.cost.input / 1000000) * usage.input;
-	usage.cost.output = (model.cost.output / 1000000) * usage.output;
-	usage.cost.cacheRead = (model.cost.cacheRead / 1000000) * usage.cacheRead;
-	usage.cost.cacheWrite = (model.cost.cacheWrite / 1000000) * usage.cacheWrite;
-	usage.cost.total = usage.cost.input + usage.cost.output + usage.cost.cacheRead + usage.cost.cacheWrite;
-	return usage.cost;
-}
-
-/**
- * Check if a model supports xhigh thinking level.
- *
- * Reads from `model.capabilities.supportsXhigh` — set via CAPABILITY_PATCHES
- * for generated models or declared directly in custom model definitions.
- * Do not add model-ID or provider-name checks here; update CAPABILITY_PATCHES instead.
- */
-export function supportsXhigh<TApi extends Api>(model: Model<TApi>): boolean {
-	return model.capabilities?.supportsXhigh ?? false;
-}
-
-/**
- * Check if two models are equal by comparing both their id and provider.
- * Returns false if either model is null or undefined.
- */
-export function modelsAreEqual<TApi extends Api>(
-	a: Model<TApi> | null | undefined,
-	b: Model<TApi> | null | undefined,
-): boolean {
-	if (!a || !b) return false;
-	return a.id === b.id && a.provider === b.provider;
-}
+// Backward-compatible entrypoint.
+// ADR-007 moved model registry internals to src/models/*.
+export * from "./models/index.js";

package/packages/pi-ai/src/providers/amazon-bedrock.test.ts

@@ -0,0 +1,164 @@
+/**
+ * Regression guards for #4392
+ *
+ * Verifies that `supportsAdaptiveThinking()` in amazon-bedrock.ts correctly
+ * recognises all current adaptive-thinking-capable models: opus-4-7,
+ * sonnet-4-7, and haiku-4-5 (in addition to the previously supported
+ * opus-4-6 / sonnet-4-6 family).
+ *
+ * Related: #4392 (opus-4-7 adaptive thinking not recognised on Bedrock)
+ *          #4352 (pre-existing: only opus-4-6 / sonnet-4-6 whitelisted)
+ */
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+    supportsAdaptiveThinking,
+    mapThinkingLevelToEffort,
+    buildAdditionalModelRequestFields,
+    type BedrockOptions,
+} from "./amazon-bedrock.js";
+
+import type { Model } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Create a minimal stub `Model` for the given ID to use in unit tests. */
+function makeModel(id: string): Model<"bedrock-converse-stream"> {
+    return {
+        id,
+        name: id,
+        api: "bedrock-converse-stream",
+        provider: "amazon-bedrock" as any,
+        baseUrl: "",
+        reasoning: true,
+        input: ["text"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 200000,
+        maxTokens: 32000,
+    };
+}
+
+// ---------------------------------------------------------------------------
+// supportsAdaptiveThinking — regression guards (#4392 / #4352)
+// ---------------------------------------------------------------------------
+
+describe("supportsAdaptiveThinking — regression guard #4392 / #4352: all supported models", () => {
+    it("returns true for opus-4-6 (hyphen, Bedrock ARN style)", () => {
+        assert.ok(supportsAdaptiveThinking("anthropic.claude-opus-4-6-20250514-v1:0"));
+    });
+
+    it("returns true for sonnet-4-6 (hyphen)", () => {
+        assert.ok(supportsAdaptiveThinking("anthropic.claude-sonnet-4-6-20250514-v1:0"));
+    });
+
+    it("[#4392] returns true for opus-4-7 (hyphen, Bedrock ARN style)", () => {
+        assert.ok(
+            supportsAdaptiveThinking("anthropic.claude-opus-4-7-20250514-v1:0"),
+            "opus-4-7 should support adaptive thinking (regression guard #4392)",
+        );
+    });
+
+    it("[#4392] returns true for opus-4-7 (dot separator)", () => {
+        assert.ok(
+            supportsAdaptiveThinking("anthropic.claude-opus-4.7-20250514-v1:0"),
+            "opus-4.7 (dot) should support adaptive thinking (regression guard #4392)",
+        );
+    });
+
+    it("[#4352] returns true for sonnet-4-7 (hyphen)", () => {
+        assert.ok(
+            supportsAdaptiveThinking("anthropic.claude-sonnet-4-7-20250514-v1:0"),
+            "sonnet-4-7 should support adaptive thinking (regression guard #4352)",
+        );
+    });
+
+    it("[#4352] returns true for haiku-4-5 (hyphen)", () => {
+        assert.ok(
+            supportsAdaptiveThinking("anthropic.claude-haiku-4-5-20250514-v1:0"),
+            "haiku-4-5 should support adaptive thinking (regression guard #4352)",
+        );
+    });
+});
+
+// ---------------------------------------------------------------------------
+// buildAdditionalModelRequestFields — adaptive thinking output for opus-4-7
+// Tests go through the public API surface to validate end-to-end behaviour.
+// ---------------------------------------------------------------------------
+
+describe("buildAdditionalModelRequestFields — Bug #4392: opus-4-7 must use adaptive thinking", () => {
+    const options: BedrockOptions = { reasoning: "high" };
+
+    it("[#4392] opus-4-7 Bedrock ARN → thinking.type === 'adaptive' (not budget_tokens)", () => {
+        const model = makeModel("anthropic.claude-opus-4-7-20250514-v1:0");
+        const fields = buildAdditionalModelRequestFields(model, options);
+        // Regression guard: supportsAdaptiveThinking must return true for opus-4-7
+        // so the function produces thinking.type='adaptive', not budget_tokens.
+        assert.equal(
+            fields?.thinking?.type,
+            "adaptive",
+            "opus-4-7 should produce thinking.type='adaptive', not budget_tokens",
+        );
+    });
+
+    it("[#4392] opus-4-7 dot separator → thinking.type === 'adaptive'", () => {
+        const model = makeModel("anthropic.claude-opus-4.7-20250514-v1:0");
+        const fields = buildAdditionalModelRequestFields(model, options);
+        assert.equal(
+            fields?.thinking?.type,
+            "adaptive",
+            "opus-4.7 (dot) should produce thinking.type='adaptive'",
+        );
+    });
+
+    it("[#4352] sonnet-4-7 → thinking.type === 'adaptive'", () => {
+        const model = makeModel("anthropic.claude-sonnet-4-7-20250514-v1:0");
+        const fields = buildAdditionalModelRequestFields(model, options);
+        assert.equal(
+            fields?.thinking?.type,
+            "adaptive",
+            "sonnet-4-7 should produce thinking.type='adaptive'",
+        );
+    });
+
+    it("[#4352] haiku-4-5 → thinking.type === 'adaptive'", () => {
+        const model = makeModel("anthropic.claude-haiku-4-5-20250514-v1:0");
+        const fields = buildAdditionalModelRequestFields(model, options);
+        assert.equal(
+            fields?.thinking?.type,
+            "adaptive",
+            "haiku-4-5 should produce thinking.type='adaptive'",
+        );
+    });
+});
+
+// ---------------------------------------------------------------------------
+// mapThinkingLevelToEffort — regression guard for xhigh on opus-4-7 (#4392)
+// Fixed: Bedrock provider now returns "xhigh" for 4.7+ models instead of "max".
+// ---------------------------------------------------------------------------
+
+describe("mapThinkingLevelToEffort — regression guard #4392: opus-4-7 xhigh returns 'xhigh'", () => {
+    it("[#4392] maps xhigh → 'xhigh' for opus-4-7 (native xhigh support)", () => {
+        // Regression guard: mapThinkingLevelToEffort must return "xhigh" for opus-4-7,
+        // not "max". Ensures the fix in #4392 does not regress.
+        const result = mapThinkingLevelToEffort("xhigh", "anthropic.claude-opus-4-7-20250514-v1:0");
+        assert.equal(
+            result,
+            "xhigh",
+            "opus-4-7 supports native xhigh effort — must not be clamped to 'max'",
+        );
+    });
+
+    it("[#4392] maps xhigh → 'max' for opus-4-6 (no native xhigh, clamped)", () => {
+        // This already passes — regression guard.
+        const result = mapThinkingLevelToEffort("xhigh", "anthropic.claude-opus-4-6-20250514-v1:0");
+        assert.equal(result, "max");
+    });
+
+    it("maps high → 'high' for opus-4-7 (not affected by bug)", () => {
+        const result = mapThinkingLevelToEffort("high", "anthropic.claude-opus-4-7-20250514-v1:0");
+        assert.equal(result, "high");
+    });
+});

package/packages/pi-ai/src/providers/amazon-bedrock.ts

@@ -45,6 +45,7 @@ import { sanitizeSurrogates } from "../utils/sanitize-unicode.js";
 import { adjustMaxTokensForThinking, buildBaseOptions, clampReasoning } from "./simple-options.js";
 import { transformMessagesWithReport } from "./transform-messages.js";
 
+/** Stream options specific to the Amazon Bedrock converse-stream provider, including region, reasoning, and caching knobs. */
 export interface BedrockOptions extends StreamOptions {
 	region?: string;
 	profile?: string;
@@ -57,8 +58,10 @@ export interface BedrockOptions extends StreamOptions {
 	interleavedThinking?: boolean;
 }
 
+/** Internal working type that annotates content blocks with a streaming index and partial JSON accumulator. */
 type Block = (TextContent | ThinkingContent | ToolCall) & { index?: number; partialJson?: string };
 
+/** Stream a conversation turn via Amazon Bedrock's converse-stream API. */
 export const streamBedrock: StreamFunction<"bedrock-converse-stream", BedrockOptions> = (
 	model: Model<"bedrock-converse-stream">,
 	context: Context,
@@ -216,6 +219,7 @@ export const streamBedrock: StreamFunction<"bedrock-converse-stream", BedrockOpt
 	return stream;
 };
 
+/** Simplified entry point for Bedrock streaming; resolves thinking budgets and adaptive-thinking support. */
 export const streamSimpleBedrock: StreamFunction<"bedrock-converse-stream", SimpleStreamOptions> = (
 	model: Model<"bedrock-converse-stream">,
 	context: Context,
@@ -260,6 +264,7 @@ export const streamSimpleBedrock: StreamFunction<"bedrock-converse-stream", Simp
 	} satisfies BedrockOptions);
 };
 
+/** Handle a `contentBlockStart` event, initialising a new tool-call block when a tool-use start arrives. */
 function handleContentBlockStart(
 	event: ContentBlockStartEvent,
 	blocks: Block[],
@@ -283,6 +288,7 @@ function handleContentBlockStart(
 	}
 }
 
+/** Handle a `contentBlockDelta` event, appending text, tool-input JSON, or reasoning content to the active block. */
 function handleContentBlockDelta(
 	event: ContentBlockDeltaEvent,
 	blocks: Block[],
@@ -341,6 +347,7 @@ function handleContentBlockDelta(
 	}
 }
 
+/** Handle a `metadata` event, updating token-usage counters and cost on the output message. */
 function handleMetadata(
 	event: ConverseStreamMetadataEvent,
 	model: Model<"bedrock-converse-stream">,
@@ -356,6 +363,7 @@ function handleMetadata(
 	}
 }
 
+/** Handle a `contentBlockStop` event, finalising the block and pushing the appropriate completion event. */
 function handleContentBlockStop(
 	event: ContentBlockStopEvent,
 	blocks: Block[],
@@ -383,21 +391,33 @@ function handleContentBlockStop(
 }
 
 /**
- * Check if the model supports adaptive thinking (Opus 4.6 and Sonnet 4.6).
+ * Check if the model supports adaptive thinking (Opus 4.6/4.7, Sonnet 4.6/4.7, Haiku 4.5).
+ * @internal exported for testing only
  */
-function supportsAdaptiveThinking(modelId: string): boolean {
+export function supportsAdaptiveThinking(modelId: string): boolean {
 	return (
 		modelId.includes("opus-4-6") ||
 		modelId.includes("opus-4.6") ||
+		modelId.includes("opus-4-7") ||
+		modelId.includes("opus-4.7") ||
 		modelId.includes("sonnet-4-6") ||
-		modelId.includes("sonnet-4.6")
+		modelId.includes("sonnet-4.6") ||
+		modelId.includes("sonnet-4-7") ||
+		modelId.includes("sonnet-4.7") ||
+		modelId.includes("haiku-4-5") ||
+		modelId.includes("haiku-4.5")
 	);
 }
 
-function mapThinkingLevelToEffort(
+/**
+ * Maps a reasoning/thinking level to the Bedrock effort string for the given model.
+ * Returns `"xhigh"` for 4.7+ models and `"max"` for older ones; `"low"` for minimal/low.
+ * @internal exported for testing only
+ */
+export function mapThinkingLevelToEffort(
 	level: SimpleStreamOptions["reasoning"],
 	modelId: string,
-): "low" | "medium" | "high" | "max" {
+): "low" | "medium" | "high" | "xhigh" | "max" {
 	switch (level) {
 		case "minimal":
 		case "low":
@@ -407,7 +427,9 @@ function mapThinkingLevelToEffort(
 		case "high":
 			return "high";
 		case "xhigh":
-			return modelId.includes("opus-4-6") || modelId.includes("opus-4.6") ? "max" : "high";
+			if (modelId.includes("opus-4-7") || modelId.includes("opus-4.7")) return "xhigh";
+			if (modelId.includes("opus-4-6") || modelId.includes("opus-4.6")) return "max";
+			return "high";
 		default:
 			return "high";
 	}
@@ -457,6 +479,7 @@ function supportsThinkingSignature(model: Model<"bedrock-converse-stream">): boo
 	return id.includes("anthropic.claude") || id.includes("anthropic/claude");
 }
 
+/** Build the Bedrock system-prompt block array, appending a cache point for supported models when caching is enabled. */
 function buildSystemPrompt(
 	systemPrompt: string | undefined,
 	model: Model<"bedrock-converse-stream">,
@@ -476,11 +499,13 @@ function buildSystemPrompt(
 	return blocks;
 }
 
+/** Sanitise a tool-call ID to alphanumeric, underscore, and hyphen characters (max 64 chars) for Bedrock compatibility. */
 function normalizeToolCallId(id: string): string {
 	const sanitized = id.replace(/[^a-zA-Z0-9_-]/g, "_");
 	return sanitized.length > 64 ? sanitized.slice(0, 64) : sanitized;
 }
 
+/** Convert GSD context messages to the Bedrock `Message[]` format, collapsing consecutive tool-result turns into a single user message. */
 function convertMessages(
 	context: Context,
 	model: Model<"bedrock-converse-stream">,
@@ -630,6 +655,7 @@ function convertMessages(
 	return result;
 }
 
+/** Convert GSD tool definitions and tool-choice preference to a Bedrock `ToolConfiguration`, appending a cache point for supported models. */
 function convertToolConfig(
 	tools: Tool[] | undefined,
 	toolChoice: BedrockOptions["toolChoice"],
@@ -673,6 +699,7 @@ function convertToolConfig(
 	return { tools: bedrockTools, toolChoice: bedrockToolChoice };
 }
 
+/** Map a Bedrock stop-reason string to GSD's internal `StopReason`. */
 function mapStopReason(reason: string | undefined): StopReason {
 	switch (reason) {
 		case BedrockStopReason.END_TURN:
@@ -688,7 +715,13 @@ function mapStopReason(reason: string | undefined): StopReason {
 	}
 }
 
-function buildAdditionalModelRequestFields(
+/**
+ * Builds the Bedrock `additionalModelRequestFields` payload for Claude models.
+ * Handles adaptive vs. budget-based thinking, beta flags, and xhigh-to-max clamping
+ * for models that lack native xhigh support.
+ * @internal exported for testing only
+ */
+export function buildAdditionalModelRequestFields(
 	model: Model<"bedrock-converse-stream">,
 	options: BedrockOptions,
 ): Record<string, any> | undefined {
@@ -733,6 +766,7 @@ function buildAdditionalModelRequestFields(
 	return undefined;
 }
 
+/** Convert a base64-encoded image to a Bedrock image content block with the appropriate `ImageFormat`. */
 function createImageBlock(mimeType: string, data: string) {
 	let format: ImageFormat;
 	switch (mimeType) {