@f5-sales-demo/pi-ai 19.90.0 → 19.91.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/pi-ai",
-	"version": "19.90.0",
+	"version": "19.91.0",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -41,11 +41,11 @@
 		"generate-models": "bun scripts/generate-models.ts"
 	},
 	"dependencies": {
-		"@anthropic-ai/sdk": "^0.78",
+		"@anthropic-ai/sdk": "^0.115",
 		"@aws-sdk/client-bedrock-runtime": "^3",
 		"@bufbuild/protobuf": "^2.11",
-		"@google/genai": "^1.43",
-		"@f5-sales-demo/pi-utils": "19.90.0",
+		"@google/genai": "^2.13",
+		"@f5-sales-demo/pi-utils": "19.91.0",
 		"@sinclair/typebox": "^0.34",
 		"@smithy/node-http-handler": "^4.4",
 		"ajv": "^8.20",

package/src/model-thinking.ts

@@ -1,21 +1,51 @@
 import { resolveOpenAICompat } from "./providers/openai-completions-compat";
 import type { Api, Model as ApiModel, ThinkingConfig } from "./types";
 
-/** User-facing thinking levels, ordered least to most intensive. */
+/**
+ * User-facing thinking levels, ordered least to most intensive.
+ *
+ * `Minimal` is xcsh-only — no provider accepts it on the wire (Anthropic rejects
+ * it with `output_config.effort: Input should be 'low', 'medium', 'high', 'xhigh'
+ * or 'max'`), so every mapper must translate it down.
+ */
 export const enum Effort {
 	Minimal = "minimal",
 	Low = "low",
 	Medium = "medium",
 	High = "high",
 	XHigh = "xhigh",
+	Max = "max",
+}
+
+/**
+ * Anthropic's `output_config.effort` enum, verbatim. Authority is the API's own
+ * validation error: `Input should be 'low', 'medium', 'high', 'xhigh' or 'max'`.
+ * Deliberately excludes xcsh's `minimal`, which the API rejects.
+ */
+export type AnthropicAdaptiveEffort = "low" | "medium" | "high" | "xhigh" | "max";
+
+/** Effort levels for providers whose wire enum stops at `xhigh` (no `max`). */
+export type EffortThroughXHigh = "minimal" | "low" | "medium" | "high" | "xhigh";
+
+/**
+ * Clamp an effort to a provider whose wire enum has no `max` (OpenAI-compat
+ * reasoning_effort, GitLab Duo, Kimi, Synthetic, …). `requireSupportedEffort`
+ * already keeps `Max` out of those providers at runtime — because their
+ * supported-effort lists exclude it — but the wire types can't prove that, and
+ * clamping is the safe direction if a caller bypasses the range check.
+ */
+export function clampEffortThroughXHigh(effort: Effort): EffortThroughXHigh {
+	return effort === Effort.Max ? Effort.XHigh : effort;
 }
 
+/** Order is load-bearing: `indexOf` drives expandEffortRange/requireSupportedEffort. */
 export const THINKING_EFFORTS: readonly Effort[] = [
 	Effort.Minimal,
 	Effort.Low,
 	Effort.Medium,
 	Effort.High,
 	Effort.XHigh,
+	Effort.Max,
 ];
 
 const DEFAULT_REASONING_EFFORTS: readonly Effort[] = [Effort.Minimal, Effort.Low, Effort.Medium, Effort.High];
@@ -26,6 +56,18 @@ const DEFAULT_REASONING_EFFORTS_WITH_XHIGH: readonly Effort[] = [
 	Effort.High,
 	Effort.XHigh,
 ];
+/**
+ * Anthropic 4.6+/5-era range. These models accept the full API enum, including
+ * `xhigh` (Anthropic's recommended setting for coding/agentic work) and `max`.
+ */
+const ANTHROPIC_ADAPTIVE_EFFORTS: readonly Effort[] = [
+	Effort.Minimal,
+	Effort.Low,
+	Effort.Medium,
+	Effort.High,
+	Effort.XHigh,
+	Effort.Max,
+];
 const GEMINI_3_PRO_EFFORTS: readonly Effort[] = [Effort.Low, Effort.High];
 const GEMINI_3_FLASH_EFFORTS: readonly Effort[] = [Effort.Minimal, Effort.Low, Effort.Medium, Effort.High];
 const GPT_5_2_PLUS_EFFORTS: readonly Effort[] = [Effort.Low, Effort.Medium, Effort.High, Effort.XHigh];
@@ -250,15 +292,22 @@ export function mapEffortToGoogleThinkingLevel<TApi extends Api>(
 			return "MEDIUM";
 		case Effort.High:
 		case Effort.XHigh:
+		case Effort.Max:
 			return "HIGH";
 	}
 }
 
-/** Maps a normalized thinking effort to Anthropic adaptive effort values. */
+/**
+ * Maps a normalized thinking effort to Anthropic adaptive effort values.
+ *
+ * The API enum is `low | medium | high | xhigh | max` (per its own validation
+ * error). `Minimal` has no wire equivalent and is translated down to `low` —
+ * sending `"minimal"` is a 400.
+ */
 export function mapEffortToAnthropicAdaptiveEffort<TApi extends Api>(
 	model: ApiModel<TApi>,
 	effort: Effort,
-): "low" | "medium" | "high" | "max" {
+): AnthropicAdaptiveEffort {
 	switch (requireSupportedEffort(model, effort)) {
 		case Effort.Minimal:
 		case Effort.Low:
@@ -268,6 +317,8 @@ export function mapEffortToAnthropicAdaptiveEffort<TApi extends Api>(
 		case Effort.High:
 			return "high";
 		case Effort.XHigh:
+			return "xhigh";
+		case Effort.Max:
 			return "max";
 	}
 }
@@ -398,7 +449,15 @@ function inferAnthropicSupportedEfforts<TApi extends Api>(
 		(model.api === "anthropic-messages" || model.api === "bedrock-converse-stream") &&
 		semverGte(parsedModel.version, "4.6")
 	) {
-		return parsedModel.kind === "opus" ? DEFAULT_REASONING_EFFORTS_WITH_XHIGH : DEFAULT_REASONING_EFFORTS;
+		// Opus 4.6+ and Sonnet 5+ accept the extended range. Sonnet 4.6 tops out at
+		// `high` — the reason this can't key on version alone (#2341).
+		const extended = parsedModel.kind === "opus" || semverGte(parsedModel.version, "5.0");
+		if (!extended) return DEFAULT_REASONING_EFFORTS;
+		// `max` is only claimed for the first-party Messages API, where the enum was
+		// verified against the live gateway. Bedrock's effort support is not verified
+		// here, so it keeps the pre-existing `xhigh` ceiling rather than being widened
+		// on an assumption.
+		return model.api === "anthropic-messages" ? ANTHROPIC_ADAPTIVE_EFFORTS : DEFAULT_REASONING_EFFORTS_WITH_XHIGH;
 	}
 	return inferFallbackEfforts(model);
 }

package/src/models.json

@@ -2647,7 +2647,7 @@
 			"thinking": {
 				"mode": "anthropic-adaptive",
 				"minLevel": "minimal",
-				"maxLevel": "xhigh"
+				"maxLevel": "max"
 			}
 		},
 		"claude-sonnet-4-0": {
@@ -2800,7 +2800,7 @@
 			"thinking": {
 				"mode": "anthropic-adaptive",
 				"minLevel": "minimal",
-				"maxLevel": "xhigh"
+				"maxLevel": "max"
 			}
 		}
 	},

package/src/providers/amazon-bedrock.ts

@@ -659,6 +659,7 @@ function buildAdditionalModelRequestFields(
 		medium: 8192,
 		high: 16384,
 		xhigh: 32768,
+		max: 65536,
 	};
 	const budget = options.thinkingBudgets?.[level] ?? defaultBudgets[level];
 

package/src/providers/anthropic.ts

@@ -3,12 +3,13 @@ import * as fs from "node:fs";
 import * as tls from "node:tls";
 import Anthropic, { type ClientOptions as AnthropicSdkClientOptions } from "@anthropic-ai/sdk";
 import type {
+	CitationsDelta,
 	ContentBlockParam,
 	MessageCreateParamsStreaming,
 	MessageParam,
 } from "@anthropic-ai/sdk/resources/messages";
 import { $env, abortableSleep, isEnoent } from "@f5-sales-demo/pi-utils";
-import { mapEffortToAnthropicAdaptiveEffort } from "../model-thinking";
+import { type AnthropicAdaptiveEffort, mapEffortToAnthropicAdaptiveEffort } from "../model-thinking";
 import { calculateCost } from "../models";
 import { getEnvApiKey, OUTPUT_FALLBACK_BUFFER } from "../stream";
 import type {
@@ -30,6 +31,7 @@ import type {
 	ToolCall,
 	ToolResultMessage,
 	Usage,
+	WebCitation,
 } from "../types";
 import { isAnthropicOAuthToken, normalizeToolCallId, resolveCacheRetention } from "../utils";
 import { createAbortSourceTracker } from "../utils/abort";
@@ -355,7 +357,11 @@ function convertContentBlocks(content: (TextContent | ImageContent)[]):
 	return blocks;
 }
 
-export type AnthropicEffort = "low" | "medium" | "high" | "max";
+/**
+ * Anthropic's `output_config.effort` enum. Single source of truth lives in
+ * model-thinking so the mapper and this raw-passthrough path cannot drift.
+ */
+export type AnthropicEffort = AnthropicAdaptiveEffort;
 
 export interface AnthropicOptions extends StreamOptions {
 	/**
@@ -625,6 +631,24 @@ export function isProviderRetryableError(error: unknown): boolean {
 	);
 }
 
+/**
+ * Map an Anthropic `citations_delta` citation to a `WebCitation`.
+ *
+ * Only web-search citations are carried: the char/page/content-block locations belong to the
+ * document-citations API, which cites user-supplied documents rather than search results and has
+ * no source URL to render as a chip.
+ */
+function mapAnthropicWebCitation(citation: CitationsDelta["citation"]): WebCitation | undefined {
+	if (citation.type !== "web_search_result_location") return undefined;
+	return {
+		type: "web_search_result_location",
+		url: citation.url,
+		...(citation.title ? { title: citation.title } : {}),
+		...(citation.cited_text ? { citedText: citation.cited_text } : {}),
+		...(citation.encrypted_index ? { encryptedIndex: citation.encrypted_index } : {}),
+	};
+}
+
 function createEmptyUsage(premiumRequests?: number): Usage {
 	return {
 		input: 0,
@@ -733,6 +757,19 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 				const anthropicRequest = client.messages.create({ ...params, stream: true }, { signal: requestSignal });
 				let streamedReplayUnsafeContent = false;
 
+				// SERVER-SIDE tools (Anthropic's built-in web search) are executed by the provider,
+				// so their blocks are deliberately NOT pushed into `output.content`: there is nothing
+				// for the agent loop to dispatch, and keeping their `encrypted_content` out of history
+				// avoids the byte-exact echo requirement that would 400 a follow-up turn. They are
+				// tracked here only long enough to report progress — keyed by the stream's block index
+				// (to accumulate the query) and by tool id (to name the matching result block).
+				// Declared inside the retry loop so a replayed attempt starts clean.
+				const serverToolUses = new Map<
+					number,
+					{ id: string; name: string; partialJson: string; inlineInput: unknown }
+				>();
+				const serverToolNames = new Map<string, string>();
+
 				try {
 					const { data: anthropicStream } = await anthropicRequest.withResponse();
 					const firstEventWatchdog = createFirstEventWatchdog(firstEventTimeoutMs, () =>
@@ -821,6 +858,30 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 									contentIndex: output.content.length - 1,
 									partial: output,
 								});
+							} else if (event.content_block.type === "server_tool_use") {
+								// Progress-only: remember the call so its query can be reported once the
+								// input JSON has finished streaming (see content_block_stop).
+								serverToolUses.set(event.index, {
+									id: event.content_block.id,
+									name: event.content_block.name,
+									partialJson: "",
+									// Nothing obliges the provider to stream the input as deltas — it may
+									// arrive whole right here. Kept as the fallback for the query.
+									inlineInput: event.content_block.input,
+								});
+								serverToolNames.set(event.content_block.id, event.content_block.name);
+							} else if (event.content_block.type === "web_search_tool_result") {
+								const toolId = event.content_block.tool_use_id;
+								const content = event.content_block.content;
+								stream.push({
+									type: "server_tool_end",
+									toolName: serverToolNames.get(toolId) ?? "web_search",
+									toolId,
+									...(Array.isArray(content)
+										? { resultCount: content.length }
+										: { errorCode: content.error_code }),
+									partial: output,
+								});
 							}
 						} else if (event.type === "content_block_delta") {
 							if (event.delta.type === "text_delta") {
@@ -848,17 +909,31 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 									});
 								}
 							} else if (event.delta.type === "input_json_delta") {
+								const serverToolUse = serverToolUses.get(event.index);
+								if (serverToolUse) {
+									// A server-side tool's input (the search query). Accumulated but not
+									// streamed as a toolcall_delta — there is no toolCall block to attach to.
+									serverToolUse.partialJson += event.delta.partial_json;
+								} else {
+									const index = blocks.findIndex(b => b.index === event.index);
+									const block = blocks[index];
+									if (block && block.type === "toolCall") {
+										block.partialJson += event.delta.partial_json;
+										block.arguments = parseStreamingJson(block.partialJson);
+										stream.push({
+											type: "toolcall_delta",
+											contentIndex: index,
+											delta: event.delta.partial_json,
+											partial: output,
+										});
+									}
+								}
+							} else if (event.delta.type === "citations_delta") {
 								const index = blocks.findIndex(b => b.index === event.index);
 								const block = blocks[index];
-								if (block && block.type === "toolCall") {
-									block.partialJson += event.delta.partial_json;
-									block.arguments = parseStreamingJson(block.partialJson);
-									stream.push({
-										type: "toolcall_delta",
-										contentIndex: index,
-										delta: event.delta.partial_json,
-										partial: output,
-									});
+								const citation = mapAnthropicWebCitation(event.delta.citation);
+								if (block && block.type === "text" && citation) {
+									block.citations = [...(block.citations ?? []), citation];
 								}
 							} else if (event.delta.type === "signature_delta") {
 								const index = blocks.findIndex(b => b.index === event.index);
@@ -869,6 +944,28 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 								}
 							}
 						} else if (event.type === "content_block_stop") {
+							const serverToolUse = serverToolUses.get(event.index);
+							if (serverToolUse) {
+								// The query has finished streaming, so the activity row can name what is
+								// being searched for. Reported here rather than at content_block_start
+								// because that is the first moment the query is known — and it still lands
+								// well before the provider's search completes.
+								serverToolUses.delete(event.index);
+								const streamed = parseStreamingJson(serverToolUse.partialJson) as
+									| { query?: unknown }
+									| undefined;
+								const inline = serverToolUse.inlineInput as { query?: unknown } | undefined;
+								const rawQuery = typeof streamed?.query === "string" ? streamed.query : inline?.query;
+								const query = typeof rawQuery === "string" && rawQuery.length > 0 ? rawQuery : undefined;
+								stream.push({
+									type: "server_tool_start",
+									toolName: serverToolUse.name,
+									toolId: serverToolUse.id,
+									...(query === undefined ? {} : { query }),
+									partial: output,
+								});
+								continue;
+							}
 							const index = blocks.findIndex(b => b.index === event.index);
 							const block = blocks[index];
 							if (block) {

package/src/providers/gitlab-duo.ts

@@ -1,3 +1,4 @@
+import { clampEffortThroughXHigh } from "../model-thinking";
 import { ANTHROPIC_THINKING, mapAnthropicToolChoice } from "../stream";
 import type { Api, Context, Model, SimpleStreamOptions } from "../types";
 import { AssistantMessageEventStream } from "../utils/event-stream";
@@ -301,6 +302,7 @@ export function streamGitLabDuo(
 								thinkingBudgetTokens: reasoningEffort
 									? (options.thinkingBudgets?.[reasoningEffort] ?? ANTHROPIC_THINKING[reasoningEffort])
 									: undefined,
+								// Anthropic path — takes the full ladder, no clamp.
 								reasoning: reasoningEffort,
 								toolChoice: mapAnthropicToolChoice(options.toolChoice),
 							},
@@ -331,7 +333,7 @@ export function streamGitLabDuo(
 									sessionId: options.sessionId,
 									providerSessionState: options.providerSessionState,
 									onPayload: options.onPayload,
-									reasoning: reasoningEffort,
+									reasoning: reasoningEffort && clampEffortThroughXHigh(reasoningEffort),
 									toolChoice: options.toolChoice,
 								} satisfies OpenAIResponsesOptions,
 							)
@@ -360,7 +362,7 @@ export function streamGitLabDuo(
 									sessionId: options.sessionId,
 									providerSessionState: options.providerSessionState,
 									onPayload: options.onPayload,
-									reasoning: reasoningEffort,
+									reasoning: reasoningEffort && clampEffortThroughXHigh(reasoningEffort),
 									toolChoice: options.toolChoice,
 								} satisfies OpenAICompletionsOptions,
 							);

package/src/providers/kimi.ts

@@ -1,3 +1,4 @@
+import { clampEffortThroughXHigh } from "../model-thinking";
 /**
  * Kimi Code provider - wraps OpenAI or Anthropic API based on format setting.
  *
@@ -104,7 +105,7 @@ export function streamKimi(
 					headers: mergedHeaders,
 					sessionId: options?.sessionId,
 					onPayload: options?.onPayload,
-					reasoning: reasoningEffort,
+					reasoning: reasoningEffort && clampEffortThroughXHigh(reasoningEffort),
 				});
 
 				for await (const event of innerStream) {

package/src/providers/openai-codex/request-transformer.ts

@@ -1,5 +1,5 @@
 import type { Effort } from "../../model-thinking";
-import { requireSupportedEffort } from "../../model-thinking";
+import { clampEffortThroughXHigh, requireSupportedEffort } from "../../model-thinking";
 import type { Api, Model } from "../../types";
 
 export interface ReasoningConfig {
@@ -53,8 +53,12 @@ export interface RequestBody {
 
 function getReasoningConfig(model: Model<Api>, options: CodexRequestOptions): ReasoningConfig {
 	return {
+		// Codex's reasoning effort has no `max`; clamp so the ladder's top level
+		// degrades to `xhigh` instead of emitting a value Codex would reject.
 		effort:
-			options.reasoningEffort === "none" ? "none" : requireSupportedEffort(model, options.reasoningEffort as Effort),
+			options.reasoningEffort === "none"
+				? "none"
+				: clampEffortThroughXHigh(requireSupportedEffort(model, options.reasoningEffort as Effort)),
 		summary: options.reasoningSummary ?? "detailed",
 	};
 }

package/src/providers/synthetic.ts

@@ -1,3 +1,4 @@
+import { clampEffortThroughXHigh } from "../model-thinking";
 /**
  * Synthetic provider - wraps OpenAI or Anthropic API based on format setting.
  *
@@ -107,7 +108,7 @@ export function streamSynthetic(
 					headers: mergedHeaders,
 					sessionId: options?.sessionId,
 					onPayload: options?.onPayload,
-					reasoning: reasoningEffort,
+					reasoning: reasoningEffort && clampEffortThroughXHigh(reasoningEffort),
 				});
 
 				for await (const event of innerStream) {

package/src/stream.ts

@@ -5,6 +5,8 @@ import { $env, $pickenv } from "@f5-sales-demo/pi-utils";
 import { getCustomApi } from "./api-registry";
 import type { Effort } from "./model-thinking";
 import {
+	clampEffortThroughXHigh,
+	type EffortThroughXHigh,
 	mapEffortToAnthropicAdaptiveEffort,
 	mapEffortToGoogleThinkingLevel,
 	requireSupportedEffort,
@@ -317,6 +319,7 @@ export const ANTHROPIC_THINKING: Record<Effort, number> = {
 	medium: 8192,
 	high: 16384,
 	xhigh: 32768,
+	max: 65536,
 };
 
 const GOOGLE_THINKING: Record<Effort, number> = {
@@ -325,6 +328,8 @@ const GOOGLE_THINKING: Record<Effort, number> = {
 	medium: 8192,
 	high: 16384,
 	xhigh: 24575,
+	// Google caps the thinking budget here; `max` cannot exceed it.
+	max: 24575,
 };
 
 const BEDROCK_CLAUDE_THINKING: Record<Effort, number> = {
@@ -333,6 +338,8 @@ const BEDROCK_CLAUDE_THINKING: Record<Effort, number> = {
 	medium: 8192,
 	high: 16384,
 	xhigh: 16384,
+	// Bedrock Claude caps the thinking budget here; `max` cannot exceed it.
+	max: 16384,
 };
 
 function resolveBedrockThinkingBudget(
@@ -394,10 +401,12 @@ function mapOpenAiToolChoice(choice?: ToolChoice): OpenAICompletionsOptions["too
 function resolveOpenAiReasoningEffort<TApi extends Api>(
 	model: Model<TApi>,
 	options?: SimpleStreamOptions,
-): Effort | undefined {
+): EffortThroughXHigh | undefined {
 	const reasoning = options?.reasoning;
 	if (!reasoning || !model.reasoning) return undefined;
-	return requireSupportedEffort(model, reasoning);
+	// OpenAI-compat `reasoning_effort` has no `max`; clamp rather than emit a
+	// value the provider would reject.
+	return clampEffortThroughXHigh(requireSupportedEffort(model, reasoning));
 }
 
 const castApi = <TApi extends Api>(api: OptionsForApi<TApi>): OptionsForApi<Api> => api as OptionsForApi<Api>;

package/src/types.ts

@@ -252,10 +252,33 @@ export interface TextSignatureV1 {
 	phase?: "commentary" | "final_answer";
 }
 
+/**
+ * A structured citation annotating a span of assistant text, produced by a provider's
+ * SERVER-SIDE search tool (Anthropic `citations_delta` → `web_search_result_location`).
+ *
+ * Carries the source title/url so hosts can render precise "Sources" chips instead of
+ * regex-scraping URLs out of the prose.
+ */
+export interface WebCitation {
+	type: "web_search_result_location";
+	url: string;
+	title?: string;
+	/** The span of source material the assistant drew on. */
+	citedText?: string;
+	/**
+	 * Opaque provider index for the cited result. Retained for fidelity only — it is never
+	 * re-sent, because echoing a provider's encrypted citation fields back on a later turn
+	 * must be byte-exact or the request is rejected.
+	 */
+	encryptedIndex?: string;
+}
+
 export interface TextContent {
 	type: "text";
 	text: string;
 	textSignature?: string; // e.g., for OpenAI responses, message metadata (legacy id string or TextSignatureV1 JSON)
+	/** Structured citations for this span, when the provider ran a server-side search. */
+	citations?: WebCitation[];
 }
 
 export interface ThinkingContent {
@@ -429,6 +452,32 @@ export type AssistantMessageEvent =
 	| { type: "toolcall_start"; contentIndex: number; partial: AssistantMessage }
 	| { type: "toolcall_delta"; contentIndex: number; delta: string; partial: AssistantMessage }
 	| { type: "toolcall_end"; contentIndex: number; toolCall: ToolCall; partial: AssistantMessage }
+	/**
+	 * A provider-SIDE tool (e.g. Anthropic's built-in web search) started running.
+	 *
+	 * Purely a progress signal so hosts can show a live activity row — the provider executes
+	 * these itself, so unlike `toolcall_*` there is nothing for the agent loop to dispatch and
+	 * no content block is added to the message.
+	 */
+	| {
+			type: "server_tool_start";
+			contentIndex?: undefined;
+			toolName: string;
+			toolId: string;
+			/** The search query, when the provider streamed one. */
+			query?: string;
+			partial: AssistantMessage;
+	  }
+	/** A provider-side tool finished: either it returned results, or it failed. */
+	| {
+			type: "server_tool_end";
+			contentIndex?: undefined;
+			toolName: string;
+			toolId: string;
+			resultCount?: number;
+			errorCode?: string;
+			partial: AssistantMessage;
+	  }
 	| {
 			type: "done";
 			contentIndex?: undefined;