gsd-pi 2.75.0 → 2.76.0-dev.4100bd590

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) {

package/packages/pi-ai/src/providers/anthropic-auth.test.ts

@@ -4,7 +4,7 @@ import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { usesAnthropicBearerAuth } from "./anthropic.js";
+import { usesAnthropicBearerAuth, resolveAnthropicBaseUrl } from "./anthropic.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -30,3 +30,49 @@ test("createClient routes Bearer-auth providers through authToken (#3783)", () =
 		"Bearer-auth providers should send authToken instead",
 	);
 });
+
+// Minimal model stub — only the field resolveAnthropicBaseUrl cares about.
+const stubModel = { baseUrl: "https://api.anthropic.com" } as Parameters<typeof resolveAnthropicBaseUrl>[0];
+
+test("resolveAnthropicBaseUrl returns model.baseUrl when ANTHROPIC_BASE_URL is unset (#4140)", (t) => {
+	const saved = process.env.ANTHROPIC_BASE_URL;
+	t.after(() => {
+		if (saved === undefined) delete process.env.ANTHROPIC_BASE_URL;
+		else process.env.ANTHROPIC_BASE_URL = saved;
+	});
+
+	delete process.env.ANTHROPIC_BASE_URL;
+	assert.equal(resolveAnthropicBaseUrl(stubModel), "https://api.anthropic.com");
+});
+
+test("resolveAnthropicBaseUrl prefers ANTHROPIC_BASE_URL over model.baseUrl (#4140)", (t) => {
+	const saved = process.env.ANTHROPIC_BASE_URL;
+	t.after(() => {
+		if (saved === undefined) delete process.env.ANTHROPIC_BASE_URL;
+		else process.env.ANTHROPIC_BASE_URL = saved;
+	});
+
+	process.env.ANTHROPIC_BASE_URL = "https://proxy.example.com";
+	assert.equal(resolveAnthropicBaseUrl(stubModel), "https://proxy.example.com");
+});
+
+test("resolveAnthropicBaseUrl ignores whitespace-only ANTHROPIC_BASE_URL (#4140)", (t) => {
+	const saved = process.env.ANTHROPIC_BASE_URL;
+	t.after(() => {
+		if (saved === undefined) delete process.env.ANTHROPIC_BASE_URL;
+		else process.env.ANTHROPIC_BASE_URL = saved;
+	});
+
+	process.env.ANTHROPIC_BASE_URL = "   ";
+	assert.equal(resolveAnthropicBaseUrl(stubModel), "https://api.anthropic.com");
+});
+
+test("createClient uses resolveAnthropicBaseUrl for all auth paths (#4140)", () => {
+	const source = readFileSync(join(__dirname, "..", "..", "src", "providers", "anthropic.ts"), "utf-8");
+	const directUsages = (source.match(/baseURL:\s*model\.baseUrl/g) ?? []).length;
+	assert.equal(directUsages, 0, "createClient must not use model.baseUrl directly — use resolveAnthropicBaseUrl(model)");
+	assert.ok(
+		source.includes("baseURL: resolveAnthropicBaseUrl(model)"),
+		"all createClient branches should pass baseURL through resolveAnthropicBaseUrl",
+	);
+});

package/packages/pi-ai/src/providers/anthropic-bearer-auth.test.ts

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const source = readFileSync(join(import.meta.dirname, "anthropic.ts"), "utf-8");
+
+describe("anthropic bearer auth for custom providers (#3874)", () => {
+	it("treats Bearer Authorization headers as authToken-capable providers", () => {
+		assert.match(
+			source,
+			/usesAnthropicBearerAuth\(model\.provider\) \|\| hasBearerAuthorizationHeader\(model\)/,
+			"custom providers with Authorization headers should opt into bearer auth",
+		);
+		assert.match(
+			source,
+			/apiKey: usesBearerAuth \? null : apiKey/,
+			"bearer-auth providers should not send x-api-key",
+		);
+		assert.match(
+			source,
+			/authToken: usesBearerAuth \? apiKey : undefined/,
+			"bearer-auth providers should send authToken instead",
+		);
+	});
+});

package/packages/pi-ai/src/providers/anthropic-shared.test.ts

@@ -1,6 +1,6 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { convertTools, mapStopReason } from "./anthropic-shared.js";
+import { convertTools, mapStopReason, mapThinkingLevelToEffort } from "./anthropic-shared.js";
 
 const makeTool = (name: string) =>
 	({
@@ -56,6 +56,20 @@ describe("convertTools cache_control", () => {
 	});
 });
 
+describe("mapThinkingLevelToEffort", () => {
+	it("maps xhigh to max for opus-4-6 (no native xhigh support)", () => {
+		assert.equal(mapThinkingLevelToEffort("xhigh", "claude-opus-4-6"), "max");
+	});
+
+	it("maps xhigh to xhigh natively for opus-4-7", () => {
+		assert.equal(mapThinkingLevelToEffort("xhigh", "claude-opus-4-7"), "xhigh");
+	});
+
+	it("maps high to high for opus-4-7", () => {
+		assert.equal(mapThinkingLevelToEffort("high", "claude-opus-4-7"), "high");
+	});
+});
+
 describe("mapStopReason", () => {
 	it("maps end_turn to stop", () => {
 		assert.equal(mapStopReason("end_turn"), "stop");

package/packages/pi-ai/src/providers/anthropic-shared.ts

@@ -1,5 +1,7 @@
 /**
  * Shared utilities for Anthropic providers (direct API and Vertex AI).
+ * Includes message conversion, tool normalisation, cache-control helpers,
+ * adaptive-thinking detection, and the core `processAnthropicStream` pump.
  */
 import type Anthropic from "@anthropic-ai/sdk";
 import type {
@@ -35,8 +37,10 @@ import { hasXmlParameterTags, repairToolJson } from "../utils/repair-tool-json.j
 import { sanitizeSurrogates } from "../utils/sanitize-unicode.js";
 import { transformMessagesWithReport } from "./transform-messages.js";
 
-export type AnthropicEffort = "low" | "medium" | "high" | "max";
+/** Effort levels accepted by the Anthropic `output_config.effort` field. */
+export type AnthropicEffort = "low" | "medium" | "high" | "xhigh" | "max";
 
+/** Extended stream options for Anthropic-protocol providers (direct API and Vertex AI). */
 export interface AnthropicOptions extends StreamOptions {
 	thinkingEnabled?: boolean;
 	thinkingBudgetTokens?: number;
@@ -45,6 +49,7 @@ export interface AnthropicOptions extends StreamOptions {
 	toolChoice?: "auto" | "any" | "none" | { type: "tool"; name: string };
 }
 
+/** Canonical list of Claude Code built-in tool names used for case-normalisation. */
 const claudeCodeTools = [
 	"Read",
 	"Write",
@@ -65,9 +70,12 @@ const claudeCodeTools = [
 	"WebSearch",
 ];
 
+/** Lowercase-keyed lookup map built from `claudeCodeTools` for O(1) case-insensitive name resolution. */
 const ccToolLookup = new Map(claudeCodeTools.map((t) => [t.toLowerCase(), t]));
 
+/** Normalise a tool name to its canonical Claude Code casing. */
 export const toClaudeCodeName = (name: string) => ccToolLookup.get(name.toLowerCase()) ?? name;
+/** Reverse-map a Claude Code tool name back to the provider's own casing, using the tools list if available. */
 export const fromClaudeCodeName = (name: string, tools?: Tool[]) => {
 	if (tools && tools.length > 0) {
 		const lowerName = name.toLowerCase();
@@ -77,6 +85,10 @@ export const fromClaudeCodeName = (name: string, tools?: Tool[]) => {
 	return name;
 };
 
+/**
+ * Resolve cache retention preference.
+ * Defaults to "short" and uses PI_CACHE_RETENTION for backward compatibility.
+ */
 function resolveCacheRetention(cacheRetention?: CacheRetention): CacheRetention {
 	if (cacheRetention) {
 		return cacheRetention;
@@ -87,6 +99,7 @@ function resolveCacheRetention(cacheRetention?: CacheRetention): CacheRetention
 	return "short";
 }
 
+/** Resolve cache retention and return the matching Anthropic `cache_control` block. */
 export function getCacheControl(
 	baseUrl: string,
 	cacheRetention?: CacheRetention,
@@ -102,6 +115,7 @@ export function getCacheControl(
 	};
 }
 
+/** Convert GSD content blocks to the Anthropic SDK's user-message content format. */
 export function convertContentBlocks(content: (TextContent | ImageContent)[]):
 	| string
 	| Array<
@@ -148,15 +162,23 @@ export function convertContentBlocks(content: (TextContent | ImageContent)[]):
 	return blocks;
 }
 
+/** Returns true for models that support the adaptive thinking API (Opus 4.6/4.7, Sonnet 4.6/4.7, Haiku 4.5). */
 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")
 	);
 }
 
+/** Map a GSD thinking level to the corresponding Anthropic effort value; model-specific for xhigh. */
 export function mapThinkingLevelToEffort(level: string | undefined, modelId: string): AnthropicEffort {
 	switch (level) {
 		case "minimal":
@@ -168,12 +190,15 @@ export function mapThinkingLevelToEffort(level: string | undefined, modelId: str
 		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";
 	}
 }
 
+/** Returns true for low-level network errors that are safe to retry (reset, pipe, timeout, DNS). */
 export function isTransientNetworkError(error: unknown): boolean {
 	if (!(error instanceof Error)) return false;
 	const msg = error.message.toLowerCase();
@@ -192,6 +217,7 @@ export function isTransientNetworkError(error: unknown): boolean {
 	);
 }
 
+/** Parse `Retry-After` / rate-limit reset headers and return a suggested delay in milliseconds. */
 export function extractRetryAfterMs(headers: Headers | { get(name: string): string | null }, errorText = ""): number | undefined {
 	const normalizeDelay = (ms: number): number | undefined => (ms > 0 ? Math.ceil(ms + 1000) : undefined);
 
@@ -223,10 +249,12 @@ export function extractRetryAfterMs(headers: Headers | { get(name: string): stri
 	return undefined;
 }
 
+/** Sanitise a tool-call ID to only alphanumeric, underscore, and hyphen characters (max 64 chars). */
 export function normalizeToolCallId(id: string): string {
 	return id.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64);
 }
 
+/** Convert GSD messages to Anthropic SDK `MessageParam` format, applying cache control to the last user turn. */
 export function convertMessages(
 	messages: Message[],
 	model: Model<AnthropicApi>,
@@ -394,6 +422,7 @@ export function convertMessages(
 	return params;
 }
 
+/** Convert GSD tools to Anthropic SDK tool definitions, applying cache control to the last entry. */
 export function convertTools(
 	tools: Tool[],
 	isOAuthToken: boolean,
@@ -423,6 +452,7 @@ export function convertTools(
 	return result;
 }
 
+/** Build the `MessageCreateParamsStreaming` payload for an Anthropic API call. */
 export function buildParams(
 	model: Model<AnthropicApi>,
 	context: Context,
@@ -503,6 +533,7 @@ export function buildParams(
 	return params;
 }
 
+/** Map an Anthropic API stop reason string to GSD's internal `StopReason`. */
 export function mapStopReason(reason: string): StopReason {
 	switch (reason) {
 		case "end_turn":
@@ -524,6 +555,7 @@ export function mapStopReason(reason: string): StopReason {
 	}
 }
 
+/** Arguments for `processAnthropicStream`. */
 export interface StreamAnthropicArgs {
 	client: Anthropic;
 	model: Model<AnthropicApi>;
@@ -533,6 +565,7 @@ export interface StreamAnthropicArgs {
 	AnthropicSdkClass?: typeof Anthropic;
 }
 
+/** Drive an Anthropic streaming response, pushing `AssistantMessageEvent`s into `stream` until done or error. */
 export function processAnthropicStream(
 	stream: AssistantMessageEventStream,
 	args: StreamAnthropicArgs,

package/packages/pi-ai/src/providers/anthropic.ts

@@ -25,6 +25,24 @@ import {
 export type { AnthropicEffort, AnthropicOptions };
 export { extractRetryAfterMs };
 
+/**
+ * Resolve the base URL for Anthropic API requests.
+ *
+ * Resolution order:
+ * 1. ANTHROPIC_BASE_URL environment variable (if set and non-empty after trim)
+ * 2. model.baseUrl (from the model definition)
+ *
+ * This allows routing traffic through custom proxy endpoints (e.g. OpusMax,
+ * local mirrors, corporate gateways) without modifying model definitions.
+ */
+export function resolveAnthropicBaseUrl(model: Model<"anthropic-messages">): string {
+	const envBaseUrl = process.env.ANTHROPIC_BASE_URL?.trim();
+	if (envBaseUrl) {
+		return envBaseUrl;
+	}
+	return model.baseUrl;
+}
+
 let _AnthropicClass: typeof Anthropic | undefined;
 async function getAnthropicClass(): Promise<typeof Anthropic> {
 	if (!_AnthropicClass) {
@@ -48,6 +66,11 @@ export function usesAnthropicBearerAuth(provider: Model<"anthropic-messages">["p
 	return provider === "alibaba-coding-plan" || provider === "minimax" || provider === "minimax-cn";
 }
 
+function hasBearerAuthorizationHeader(model: Model<"anthropic-messages">): boolean {
+	const authHeader = model.headers?.Authorization ?? model.headers?.authorization;
+	return typeof authHeader === "string" && authHeader.trim().toLowerCase().startsWith("bearer ");
+}
+
 async function createClient(
 	model: Model<"anthropic-messages">,
 	apiKey: string,
@@ -70,7 +93,7 @@ async function createClient(
 		const client = new AnthropicClass({
 			apiKey: null,
 			authToken: apiKey,
-			baseURL: model.baseUrl,
+			baseURL: resolveAnthropicBaseUrl(model),
 			dangerouslyAllowBrowser: true,
 			defaultHeaders: mergeHeaders(
 				{
@@ -96,7 +119,7 @@ async function createClient(
 
 	// API key auth (Anthropic OAuth removed per TOS compliance — use API keys or Claude CLI)
 	// Some Anthropic-compatible providers require Bearer auth instead of x-api-key.
-	const usesBearerAuth = usesAnthropicBearerAuth(model.provider);
+	const usesBearerAuth = usesAnthropicBearerAuth(model.provider) || hasBearerAuthorizationHeader(model);
 	const client = new AnthropicClass({
 		apiKey: usesBearerAuth ? null : apiKey,
 		authToken: usesBearerAuth ? apiKey : undefined,

package/packages/pi-ai/src/providers/api-family.test.ts

@@ -0,0 +1,129 @@
+// gsd-2 / pi-ai: api-family predicate tests
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  isAnthropicApi,
+  isBedrockApi,
+  isGeminiApi,
+  isOpenAIApi,
+} from "./api-family.js";
+
+// Every api value registered via registerApiProvider() in register-builtins.ts.
+// Keep in sync with that file — the expectations below assert every api is
+// classified by exactly one family (except mistral, which is its own family
+// and belongs to none of the helpers).
+const ALL_REGISTERED_APIS = [
+  "anthropic-messages",
+  "anthropic-vertex",
+  "openai-completions",
+  "openai-responses",
+  "azure-openai-responses",
+  "openai-codex-responses",
+  "google-generative-ai",
+  "google-gemini-cli",
+  "google-vertex",
+  "bedrock-converse-stream",
+  "mistral-conversations",
+] as const;
+
+describe("isAnthropicApi", () => {
+  test("matches anthropic-messages and anthropic-vertex", () => {
+    assert.equal(isAnthropicApi({ api: "anthropic-messages" }), true);
+    assert.equal(isAnthropicApi({ api: "anthropic-vertex" }), true);
+  });
+
+  test("excludes bedrock-converse-stream (different tool schema)", () => {
+    assert.equal(isAnthropicApi({ api: "bedrock-converse-stream" }), false);
+  });
+
+  test("excludes every non-Anthropic registered api", () => {
+    const nonAnthropic = ALL_REGISTERED_APIS.filter(
+      (a) => a !== "anthropic-messages" && a !== "anthropic-vertex",
+    );
+    for (const api of nonAnthropic) {
+      assert.equal(isAnthropicApi({ api }), false, `api=${api}`);
+    }
+  });
+
+  test("tolerates null/undefined/missing api", () => {
+    assert.equal(isAnthropicApi(null), false);
+    assert.equal(isAnthropicApi(undefined), false);
+    assert.equal(isAnthropicApi({}), false);
+    assert.equal(isAnthropicApi({ api: "" }), false);
+  });
+});
+
+describe("isOpenAIApi", () => {
+  test("matches all OpenAI-shaped apis", () => {
+    for (const api of [
+      "openai-completions",
+      "openai-responses",
+      "azure-openai-responses",
+      "openai-codex-responses",
+    ]) {
+      assert.equal(isOpenAIApi({ api }), true, `api=${api}`);
+    }
+  });
+
+  test("excludes every non-OpenAI registered api", () => {
+    const nonOpenAI = ALL_REGISTERED_APIS.filter(
+      (a) =>
+        a !== "openai-completions" &&
+        a !== "openai-responses" &&
+        a !== "azure-openai-responses" &&
+        a !== "openai-codex-responses",
+    );
+    for (const api of nonOpenAI) {
+      assert.equal(isOpenAIApi({ api }), false, `api=${api}`);
+    }
+  });
+});
+
+describe("isGeminiApi", () => {
+  test("matches all Gemini-shaped apis", () => {
+    for (const api of ["google-generative-ai", "google-gemini-cli", "google-vertex"]) {
+      assert.equal(isGeminiApi({ api }), true, `api=${api}`);
+    }
+  });
+
+  test("excludes every non-Gemini registered api", () => {
+    const nonGemini = ALL_REGISTERED_APIS.filter(
+      (a) =>
+        a !== "google-generative-ai" &&
+        a !== "google-gemini-cli" &&
+        a !== "google-vertex",
+    );
+    for (const api of nonGemini) {
+      assert.equal(isGeminiApi({ api }), false, `api=${api}`);
+    }
+  });
+});
+
+describe("isBedrockApi", () => {
+  test("matches only bedrock-converse-stream", () => {
+    assert.equal(isBedrockApi({ api: "bedrock-converse-stream" }), true);
+    for (const api of ALL_REGISTERED_APIS.filter((a) => a !== "bedrock-converse-stream")) {
+      assert.equal(isBedrockApi({ api }), false, `api=${api}`);
+    }
+  });
+});
+
+describe("api-family exclusivity", () => {
+  test("every registered api belongs to exactly one family (or mistral = none)", () => {
+    for (const api of ALL_REGISTERED_APIS) {
+      const matches = [
+        isAnthropicApi({ api }),
+        isOpenAIApi({ api }),
+        isGeminiApi({ api }),
+        isBedrockApi({ api }),
+      ].filter(Boolean).length;
+      const expected = api === "mistral-conversations" ? 0 : 1;
+      assert.equal(
+        matches,
+        expected,
+        `api=${api} matched ${matches} families (expected ${expected})`,
+      );
+    }
+  });
+});