gsd-pi 2.75.0-dev.063e5a3 → 2.75.0-dev.fd2382b9f

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

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-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) {
@@ -70,7 +88,7 @@ async function createClient(
 		const client = new AnthropicClass({
 			apiKey: null,
 			authToken: apiKey,
-			baseURL: model.baseUrl,
+			baseURL: resolveAnthropicBaseUrl(model),
 			dangerouslyAllowBrowser: true,
 			defaultHeaders: mergeHeaders(
 				{

package/packages/pi-ai/src/utils/oauth/openai-codex.ts

@@ -26,6 +26,14 @@ const TOKEN_URL = "https://auth.openai.com/oauth/token";
 const REDIRECT_URI = "http://localhost:1455/auth/callback";
 const SCOPE = "openid profile email offline_access";
 const JWT_CLAIM_PATH = "https://api.openai.com/auth";
+const CHATGPT_UNSUPPORTED_MODEL_IDS = new Set([
+	"gpt-5.2-codex",
+	"gpt-5.1-codex-mini",
+	"gpt-5.1-codex-max",
+	"gpt-5.1-codex",
+	"gpt-5.1",
+	"gpt-5",
+]);
 
 const SUCCESS_HTML = `<!doctype html>
 <html lang="en">
@@ -454,4 +462,11 @@ export const openaiCodexOAuthProvider: OAuthProviderInterface = {
 	getApiKey(credentials: OAuthCredentials): string {
 		return credentials.access;
 	},
+
+	modifyModels(models) {
+		return models.filter((model) => (
+			model.provider !== "openai-codex"
+			|| !CHATGPT_UNSUPPORTED_MODEL_IDS.has(model.id)
+		));
+	},
 };