@f5xc-salesdemos/xcsh 17.4.3 → 17.4.4

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "17.4.3",
+	"version": "17.4.4",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5xc-salesdemos/xcsh",
 	"author": "Can Boluk",
@@ -46,12 +46,12 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5xc-salesdemos/xcsh-stats": "17.4.3",
-		"@f5xc-salesdemos/pi-agent-core": "17.4.3",
-		"@f5xc-salesdemos/pi-ai": "17.4.3",
-		"@f5xc-salesdemos/pi-natives": "17.4.3",
-		"@f5xc-salesdemos/pi-tui": "17.4.3",
-		"@f5xc-salesdemos/pi-utils": "17.4.3",
+		"@f5xc-salesdemos/xcsh-stats": "17.4.4",
+		"@f5xc-salesdemos/pi-agent-core": "17.4.4",
+		"@f5xc-salesdemos/pi-ai": "17.4.4",
+		"@f5xc-salesdemos/pi-natives": "17.4.4",
+		"@f5xc-salesdemos/pi-tui": "17.4.4",
+		"@f5xc-salesdemos/pi-utils": "17.4.4",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

package/src/web/search/errors.ts

@@ -0,0 +1,120 @@
+import { SearchProviderError } from "./types";
+
+export interface WebSearchError {
+	field?: string;
+	constraint?: string;
+	userMessage: string;
+	status?: number;
+	raw: unknown;
+}
+
+const FIELD_PATTERN = /tools\.\d+\.web_search_\d+\.([A-Za-z_][A-Za-z_0-9.]*?):\s*(.+?)(?:\n|$)/;
+
+const LITELLM_NOISE_PATTERNS: RegExp[] = [
+	/No fallback model group found for original model_group=[^\n]*/gi,
+	/Fallbacks=\[[^\]]*\][^\n]*/gi,
+	/Available Model Group Fallbacks=[^\n]*/gi,
+	/claude-haiku-[0-9a-z.-]+/gi,
+	/claude-[a-z0-9-]+-\d+/gi,
+	/model_group=[^\s,]+/gi,
+];
+
+function scrubLitellmNoise(text: string): string {
+	let cleaned = text;
+	for (const pattern of LITELLM_NOISE_PATTERNS) {
+		cleaned = cleaned.replace(pattern, "");
+	}
+	return cleaned
+		.replace(/\n{2,}/g, "\n")
+		.replace(/\s{2,}/g, " ")
+		.trim();
+}
+
+function fieldHint(field: string): string | undefined {
+	if (field === "user_location.country") {
+		return "user_location.country must be an ISO 3166-1 alpha-2 code (e.g. US, JP, GB)";
+	}
+	return undefined;
+}
+
+function extractRawMessage(input: unknown): string {
+	if (typeof input === "string") return input;
+	if (input instanceof SearchProviderError) return input.message;
+	if (input instanceof Error) return input.message;
+	if (input && typeof input === "object") {
+		const body = (input as { error?: { message?: unknown } }).error;
+		if (body && typeof body.message === "string") return body.message;
+	}
+	return "";
+}
+
+function tryParseJsonString(raw: string): unknown | undefined {
+	const trimmed = raw.trim();
+	if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return undefined;
+	try {
+		return JSON.parse(trimmed);
+	} catch {
+		return undefined;
+	}
+}
+
+function matchFieldPattern(text: string): RegExpMatchArray | null {
+	return text.match(FIELD_PATTERN);
+}
+
+export function parseWebSearchError(input: unknown): WebSearchError {
+	if (input instanceof SearchProviderError) {
+		if (input.status === 401 || input.status === 403) {
+			return {
+				status: input.status,
+				userMessage: `Web search authorization failed (${input.status}). Check API key or base URL.`,
+				raw: input,
+			};
+		}
+		if (input.status === 404) {
+			return {
+				status: input.status,
+				userMessage: "Web search returned 404 (model or endpoint not found).",
+				raw: input,
+			};
+		}
+	}
+
+	let bodyForFieldScan: unknown = input;
+	if (typeof input === "string") {
+		const parsed = tryParseJsonString(input);
+		if (parsed !== undefined) bodyForFieldScan = parsed;
+	}
+
+	const rawMessage = extractRawMessage(bodyForFieldScan);
+
+	if (rawMessage.length === 0) {
+		return {
+			userMessage: "web_search failed — no error detail available.",
+			raw: input,
+		};
+	}
+
+	const match = matchFieldPattern(rawMessage);
+	if (match) {
+		const field = match[1];
+		const constraint = match[2].trim();
+		const hint = fieldHint(field);
+		const userMessage = hint ? `web_search error: ${hint}.` : `web_search error: ${field} — ${constraint}.`;
+		return { field, constraint, userMessage, raw: input };
+	}
+
+	if (input instanceof Error && !(input instanceof SearchProviderError)) {
+		return {
+			userMessage: `web_search transport error: ${input.message}`,
+			raw: input,
+		};
+	}
+
+	const scrubbed = scrubLitellmNoise(rawMessage);
+	const userMessage =
+		scrubbed.length > 0
+			? `web_search failed — ${scrubbed}`
+			: "web_search failed — upstream error (details suppressed).";
+	return { userMessage, raw: input };
+}

package/src/web/search/index.ts

@@ -21,6 +21,8 @@ import webSearchSystemPrompt from "../../prompts/system/web-search.md" with { ty
 import webSearchDescription from "../../prompts/tools/web-search.md" with { type: "text" };
 import type { ToolSession } from "../../tools";
 import { formatAge } from "../../tools/render-utils";
+import { parseWebSearchError } from "./errors";
+import { normalizeUserLocation, validateWebSearchParams, type WebSearchParams } from "./params";
 import { getSearchProvider, resolveProviderChain, type SearchProvider } from "./provider";
 import { renderSearchCall, renderSearchResult, type SearchRenderDetails } from "./render";
 import type { SearchProviderId, SearchResponse } from "./types";
@@ -28,26 +30,52 @@ import { SearchProviderError } from "./types";
 
 /** Web search tool parameters schema */
 export const webSearchSchema = Type.Object({
-	query: Type.String({ description: "Search query" }),
+	query: Type.String({ description: "Search query (non-empty, whitespace-only is rejected)" }),
 	recency: Type.Optional(
 		StringEnum(["day", "week", "month", "year"], {
-			description: "Recency filter (Brave, Perplexity)",
+			description: "Recency filter. Exhaustive enum — one of: day, week, month, year.",
 		}),
 	),
-	limit: Type.Optional(Type.Number({ description: "Max results to return" })),
-	max_tokens: Type.Optional(Type.Number({ description: "Maximum output tokens" })),
-	temperature: Type.Optional(Type.Number({ description: "Sampling temperature" })),
-	num_search_results: Type.Optional(Type.Number({ description: "Number of search results to retrieve" })),
-	allowed_domains: Type.Optional(Type.Array(Type.String(), { description: "Only return results from these domains" })),
-	blocked_domains: Type.Optional(Type.Array(Type.String(), { description: "Exclude results from these domains" })),
-	max_uses: Type.Optional(Type.Number({ description: "Maximum number of web searches per request" })),
+	limit: Type.Optional(
+		Type.Number({
+			description:
+				"Post-processing cap on the number of sources surfaced in the tool result. Positive integer. Controls output verbosity; see num_search_results for backend fetch count.",
+		}),
+	),
+	max_tokens: Type.Optional(Type.Number({ description: "Maximum output tokens. Positive integer." })),
+	temperature: Type.Optional(Type.Number({ description: "Sampling temperature between 0 and 2." })),
+	num_search_results: Type.Optional(
+		Type.Number({
+			description:
+				"Number of sources the backend should fetch. Positive integer. Controls provider fetch count; see limit for output-side trimming.",
+		}),
+	),
+	allowed_domains: Type.Optional(
+		Type.Array(Type.String(), {
+			description: "Only return results from these domains. Entries must be non-empty strings.",
+		}),
+	),
+	blocked_domains: Type.Optional(
+		Type.Array(Type.String(), {
+			description: "Exclude results from these domains. Entries must be non-empty strings.",
+		}),
+	),
+	max_uses: Type.Optional(
+		Type.Number({ description: "Maximum number of web searches per request. Positive integer." }),
+	),
 	user_location: Type.Optional(
 		Type.Object(
 			{
 				type: Type.Literal("approximate"),
 				city: Type.Optional(Type.String()),
 				region: Type.Optional(Type.String()),
-				country: Type.Optional(Type.String()),
+				country: Type.Optional(
+					Type.String({
+						minLength: 2,
+						maxLength: 2,
+						description: "ISO 3166-1 alpha-2 country code (e.g. US, JP, GB)",
+					}),
+				),
 				timezone: Type.Optional(Type.String()),
 			},
 			{ description: "Approximate user location for localized results" },
@@ -96,9 +124,9 @@ function formatProviderError(error: unknown, provider: SearchProvider): string {
 			}
 			return `${getSearchProvider(error.provider).label} authorization failed (${error.status}). Check API key or base URL.`;
 		}
-		return error.message;
+		return parseWebSearchError(error).userMessage;
 	}
-	if (error instanceof Error) return error.message;
+	if (error instanceof Error) return parseWebSearchError(error).userMessage;
 	return `Unknown error from ${provider.label}`;
 }
 
@@ -168,6 +196,19 @@ async function executeSearch(
 	_toolCallId: string,
 	params: SearchQueryParams,
 ): Promise<{ content: Array<{ type: "text"; text: string }>; details: SearchRenderDetails }> {
+	const validation = validateWebSearchParams(params as WebSearchParams);
+	if (!validation.valid) {
+		const message = `web_search invalid parameter: ${validation.error}`;
+		return {
+			content: [{ type: "text" as const, text: `Error: ${message}` }],
+			details: { response: { provider: "none", sources: [] }, error: message },
+		};
+	}
+	const normalizedLocation = normalizeUserLocation(params.user_location);
+	const normalizedParams: SearchQueryParams = normalizedLocation
+		? { ...params, user_location: normalizedLocation }
+		: params;
+	params = normalizedParams;
 	const hasAnthropicOnlyParams =
 		params.allowed_domains?.length || params.blocked_domains?.length || params.max_uses || params.user_location;
 	const effectiveProvider =

package/src/web/search/params.ts

@@ -0,0 +1,129 @@
+export type WebSearchRecency = "day" | "week" | "month" | "year";
+
+export interface WebSearchUserLocation {
+	type: "approximate";
+	city?: string;
+	region?: string;
+	country?: string;
+	timezone?: string;
+}
+
+export interface WebSearchParams {
+	query: string;
+	recency?: WebSearchRecency;
+	limit?: number;
+	max_tokens?: number;
+	temperature?: number;
+	num_search_results?: number;
+	max_uses?: number;
+	allowed_domains?: string[];
+	blocked_domains?: string[];
+	user_location?: WebSearchUserLocation;
+}
+
+export type ValidationResult = { valid: true } | { valid: false; error: string };
+
+const RECENCY_VALUES: readonly WebSearchRecency[] = ["day", "week", "month", "year"] as const;
+const ISO_ALPHA2 = /^[A-Za-z]{2}$/;
+
+function fail(error: string): ValidationResult {
+	return { valid: false, error };
+}
+
+function isPositiveInteger(value: number): boolean {
+	return Number.isInteger(value) && value > 0;
+}
+
+function validatePositiveInteger(name: string, value: number | undefined): ValidationResult | null {
+	if (value === undefined) return null;
+	if (!isPositiveInteger(value)) {
+		return fail(`${name} must be a positive integer (received ${value})`);
+	}
+	return null;
+}
+
+function validateDomainList(name: string, list: string[] | undefined): ValidationResult | null {
+	if (list === undefined) return null;
+	for (const entry of list) {
+		if (typeof entry !== "string" || entry.trim().length === 0) {
+			return fail(`${name} must not contain empty or whitespace-only entries`);
+		}
+	}
+	return null;
+}
+
+function validateUserLocation(loc: WebSearchUserLocation | undefined): ValidationResult | null {
+	if (loc === undefined) return null;
+	if (loc.type !== "approximate") {
+		return fail(`user_location.type must be "approximate" (received "${String(loc.type)}")`);
+	}
+	if (loc.country !== undefined) {
+		if (typeof loc.country !== "string" || !ISO_ALPHA2.test(loc.country)) {
+			return fail(
+				`user_location.country must be an ISO 3166-1 alpha-2 code (e.g. "US", "JP", "GB") (received "${String(loc.country)}")`,
+			);
+		}
+	}
+	if (loc.city !== undefined && (typeof loc.city !== "string" || loc.city.trim().length === 0)) {
+		return fail(`user_location.city must be a non-empty string`);
+	}
+	if (loc.region !== undefined && (typeof loc.region !== "string" || loc.region.trim().length === 0)) {
+		return fail(`user_location.region must be a non-empty string`);
+	}
+	if (loc.timezone !== undefined && (typeof loc.timezone !== "string" || loc.timezone.trim().length === 0)) {
+		return fail(`user_location.timezone must be a non-empty string`);
+	}
+	return null;
+}
+
+export function validateWebSearchParams(params: WebSearchParams): ValidationResult {
+	if (typeof params.query !== "string" || params.query.trim().length === 0) {
+		return fail("query must be a non-empty string");
+	}
+
+	if (params.recency !== undefined && !RECENCY_VALUES.includes(params.recency)) {
+		return fail(
+			`recency must be one of ${RECENCY_VALUES.map(v => `"${v}"`).join(", ")} (received "${String(params.recency)}")`,
+		);
+	}
+
+	const positiveIntegerFields: [string, number | undefined][] = [
+		["num_search_results", params.num_search_results],
+		["limit", params.limit],
+		["max_tokens", params.max_tokens],
+		["max_uses", params.max_uses],
+	];
+	for (const [name, value] of positiveIntegerFields) {
+		const result = validatePositiveInteger(name, value);
+		if (result) return result;
+	}
+
+	if (params.temperature !== undefined) {
+		if (typeof params.temperature !== "number" || params.temperature < 0 || params.temperature > 2) {
+			return fail(`temperature must be a number between 0 and 2 (received ${params.temperature})`);
+		}
+	}
+
+	for (const [name, list] of [
+		["allowed_domains", params.allowed_domains],
+		["blocked_domains", params.blocked_domains],
+	] as const) {
+		const result = validateDomainList(name, list);
+		if (result) return result;
+	}
+
+	const locResult = validateUserLocation(params.user_location);
+	if (locResult) return locResult;
+
+	return { valid: true };
+}
+
+export function normalizeUserLocation(loc: WebSearchUserLocation | undefined): WebSearchUserLocation | undefined {
+	if (loc === undefined) return undefined;
+	const next: WebSearchUserLocation = { type: loc.type };
+	if (loc.city !== undefined) next.city = loc.city;
+	if (loc.region !== undefined) next.region = loc.region;
+	if (loc.timezone !== undefined) next.timezone = loc.timezone;
+	if (loc.country !== undefined) next.country = loc.country.toUpperCase();
+	return next;
+}