pi-usereq 0.6.0 → 0.10.0

package/pi.dev-src/pi-mono/ai/src/utils/overflow.ts

@@ -0,0 +1,138 @@
+import type { AssistantMessage } from "../types.js";
+
+/**
+ * Regex patterns to detect context overflow errors from different providers.
+ *
+ * These patterns match error messages returned when the input exceeds
+ * the model's context window.
+ *
+ * Provider-specific patterns (with example error messages):
+ *
+ * - Anthropic: "prompt is too long: 213462 tokens > 200000 maximum"
+ * - Anthropic: "413 {\"error\":{\"type\":\"request_too_large\",\"message\":\"Request exceeds the maximum size\"}}"
+ * - OpenAI: "Your input exceeds the context window of this model"
+ * - Google: "The input token count (1196265) exceeds the maximum number of tokens allowed (1048575)"
+ * - xAI: "This model's maximum prompt length is 131072 but the request contains 537812 tokens"
+ * - Groq: "Please reduce the length of the messages or completion"
+ * - OpenRouter: "This endpoint's maximum context length is X tokens. However, you requested about Y tokens"
+ * - llama.cpp: "the request exceeds the available context size, try increasing it"
+ * - LM Studio: "tokens to keep from the initial prompt is greater than the context length"
+ * - GitHub Copilot: "prompt token count of X exceeds the limit of Y"
+ * - MiniMax: "invalid params, context window exceeds limit"
+ * - Kimi For Coding: "Your request exceeded model token limit: X (requested: Y)"
+ * - Cerebras: "400/413 status code (no body)"
+ * - Mistral: "Prompt contains X tokens ... too large for model with Y maximum context length"
+ * - z.ai: Does NOT error, accepts overflow silently - handled via usage.input > contextWindow
+ * - Ollama: Some deployments truncate silently, others return errors like "prompt too long; exceeded max context length by X tokens"
+ */
+const OVERFLOW_PATTERNS = [
+	/prompt is too long/i, // Anthropic token overflow
+	/request_too_large/i, // Anthropic request byte-size overflow (HTTP 413)
+	/input is too long for requested model/i, // Amazon Bedrock
+	/exceeds the context window/i, // OpenAI (Completions & Responses API)
+	/input token count.*exceeds the maximum/i, // Google (Gemini)
+	/maximum prompt length is \d+/i, // xAI (Grok)
+	/reduce the length of the messages/i, // Groq
+	/maximum context length is \d+ tokens/i, // OpenRouter (all backends)
+	/exceeds the limit of \d+/i, // GitHub Copilot
+	/exceeds the available context size/i, // llama.cpp server
+	/greater than the context length/i, // LM Studio
+	/context window exceeds limit/i, // MiniMax
+	/exceeded model token limit/i, // Kimi For Coding
+	/too large for model with \d+ maximum context length/i, // Mistral
+	/model_context_window_exceeded/i, // z.ai non-standard finish_reason surfaced as error text
+	/prompt too long; exceeded (?:max )?context length/i, // Ollama explicit overflow error
+	/context[_ ]length[_ ]exceeded/i, // Generic fallback
+	/too many tokens/i, // Generic fallback
+	/token limit exceeded/i, // Generic fallback
+	/^4(?:00|13)\s*(?:status code)?\s*\(no body\)/i, // Cerebras: 400/413 with no body
+];
+
+/**
+ * Patterns that indicate non-overflow errors (e.g. rate limiting, server errors).
+ * Error messages matching any of these are excluded from overflow detection
+ * even if they also match an OVERFLOW_PATTERN.
+ *
+ * Example: Bedrock formats throttling errors as "ThrottlingException: Too many tokens,
+ * please wait before trying again." which would match the /too many tokens/i overflow
+ * pattern without this exclusion.
+ */
+const NON_OVERFLOW_PATTERNS = [
+	/^(Throttling error|Service unavailable):/i, // AWS Bedrock non-overflow errors (human-readable prefixes from formatBedrockError)
+	/rate limit/i, // Generic rate limiting
+	/too many requests/i, // Generic HTTP 429 style
+];
+
+/**
+ * Check if an assistant message represents a context overflow error.
+ *
+ * This handles two cases:
+ * 1. Error-based overflow: Most providers return stopReason "error" with a
+ *    specific error message pattern.
+ * 2. Silent overflow: Some providers accept overflow requests and return
+ *    successfully. For these, we check if usage.input exceeds the context window.
+ *
+ * ## Reliability by Provider
+ *
+ * **Reliable detection (returns error with detectable message):**
+ * - Anthropic: "prompt is too long: X tokens > Y maximum" or "request_too_large"
+ * - OpenAI (Completions & Responses): "exceeds the context window"
+ * - Google Gemini: "input token count exceeds the maximum"
+ * - xAI (Grok): "maximum prompt length is X but request contains Y"
+ * - Groq: "reduce the length of the messages"
+ * - Cerebras: 400/413 status code (no body)
+ * - Mistral: "Prompt contains X tokens ... too large for model with Y maximum context length"
+ * - OpenRouter (all backends): "maximum context length is X tokens"
+ * - llama.cpp: "exceeds the available context size"
+ * - LM Studio: "greater than the context length"
+ * - Kimi For Coding: "exceeded model token limit: X (requested: Y)"
+ *
+ * **Unreliable detection:**
+ * - z.ai: Sometimes accepts overflow silently (detectable via usage.input > contextWindow),
+ *   sometimes returns rate limit errors. Pass contextWindow param to detect silent overflow.
+ * - Ollama: May truncate input silently for some setups, but may also return explicit
+ *   overflow errors that match the patterns above. Silent truncation still cannot be
+ *   detected here because we do not know the expected token count.
+ *
+ * ## Custom Providers
+ *
+ * If you've added custom models via settings.json, this function may not detect
+ * overflow errors from those providers. To add support:
+ *
+ * 1. Send a request that exceeds the model's context window
+ * 2. Check the errorMessage in the response
+ * 3. Create a regex pattern that matches the error
+ * 4. The pattern should be added to OVERFLOW_PATTERNS in this file, or
+ *    check the errorMessage yourself before calling this function
+ *
+ * @param message - The assistant message to check
+ * @param contextWindow - Optional context window size for detecting silent overflow (z.ai)
+ * @returns true if the message indicates a context overflow
+ */
+export function isContextOverflow(message: AssistantMessage, contextWindow?: number): boolean {
+	// Case 1: Check error message patterns
+	if (message.stopReason === "error" && message.errorMessage) {
+		// Skip messages matching known non-overflow patterns (e.g. throttling / rate-limit)
+		const isNonOverflow = NON_OVERFLOW_PATTERNS.some((p) => p.test(message.errorMessage!));
+		if (!isNonOverflow && OVERFLOW_PATTERNS.some((p) => p.test(message.errorMessage!))) {
+			return true;
+		}
+	}
+
+	// Case 2: Silent overflow (z.ai style) - successful but usage exceeds context
+	if (contextWindow && message.stopReason === "stop") {
+		const inputTokens = message.usage.input + message.usage.cacheRead;
+		if (inputTokens > contextWindow) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+/**
+ * Get the overflow patterns for testing purposes.
+ */
+export function getOverflowPatterns(): RegExp[] {
+	return [...OVERFLOW_PATTERNS];
+}

package/pi.dev-src/pi-mono/ai/src/utils/sanitize-unicode.ts

@@ -0,0 +1,25 @@
+/**
+ * Removes unpaired Unicode surrogate characters from a string.
+ *
+ * Unpaired surrogates (high surrogates 0xD800-0xDBFF without matching low surrogates 0xDC00-0xDFFF,
+ * or vice versa) cause JSON serialization errors in many API providers.
+ *
+ * Valid emoji and other characters outside the Basic Multilingual Plane use properly paired
+ * surrogates and will NOT be affected by this function.
+ *
+ * @param text - The text to sanitize
+ * @returns The sanitized text with unpaired surrogates removed
+ *
+ * @example
+ * // Valid emoji (properly paired surrogates) are preserved
+ * sanitizeSurrogates("Hello 🙈 World") // => "Hello 🙈 World"
+ *
+ * // Unpaired high surrogate is removed
+ * const unpaired = String.fromCharCode(0xD83D); // high surrogate without low
+ * sanitizeSurrogates(`Text ${unpaired} here`) // => "Text  here"
+ */
+export function sanitizeSurrogates(text: string): string {
+	// Replace unpaired high surrogates (0xD800-0xDBFF not followed by low surrogate)
+	// Replace unpaired low surrogates (0xDC00-0xDFFF not preceded by high surrogate)
+	return text.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "");
+}

package/pi.dev-src/pi-mono/ai/src/utils/typebox-helpers.ts

@@ -0,0 +1,24 @@
+import { type TUnsafe, Type } from "typebox";
+
+/**
+ * Creates a string enum schema compatible with Google's API and other providers
+ * that don't support anyOf/const patterns.
+ *
+ * @example
+ * const OperationSchema = StringEnum(["add", "subtract", "multiply", "divide"], {
+ *   description: "The operation to perform"
+ * });
+ *
+ * type Operation = Static<typeof OperationSchema>; // "add" | "subtract" | "multiply" | "divide"
+ */
+export function StringEnum<T extends readonly string[]>(
+	values: T,
+	options?: { description?: string; default?: T[number] },
+): TUnsafe<T[number]> {
+	return Type.Unsafe<T[number]>({
+		type: "string",
+		enum: values as any,
+		...(options?.description && { description: options.description }),
+		...(options?.default && { default: options.default }),
+	});
+}

package/pi.dev-src/pi-mono/ai/src/utils/validation.ts

@@ -0,0 +1,324 @@
+import { Compile } from "typebox/compile";
+import type { TLocalizedValidationError } from "typebox/error";
+import { Value } from "typebox/value";
+import type { Tool, ToolCall } from "../types.js";
+
+const validatorCache = new WeakMap<object, ReturnType<typeof Compile>>();
+const TYPEBOX_KIND = Symbol.for("TypeBox.Kind");
+
+interface JsonSchemaObject {
+	type?: string | string[];
+	properties?: Record<string, JsonSchemaObject>;
+	items?: JsonSchemaObject | JsonSchemaObject[];
+	additionalProperties?: boolean | JsonSchemaObject;
+	allOf?: JsonSchemaObject[];
+	anyOf?: JsonSchemaObject[];
+	oneOf?: JsonSchemaObject[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function isJsonSchemaObject(value: unknown): value is JsonSchemaObject {
+	return isRecord(value);
+}
+
+function hasTypeBoxMetadata(schema: unknown): boolean {
+	return isRecord(schema) && Object.getOwnPropertySymbols(schema).includes(TYPEBOX_KIND);
+}
+
+function getSchemaTypes(schema: JsonSchemaObject): string[] {
+	if (typeof schema.type === "string") {
+		return [schema.type];
+	}
+	if (Array.isArray(schema.type)) {
+		return schema.type.filter((type): type is string => typeof type === "string");
+	}
+	return [];
+}
+
+function matchesJsonType(value: unknown, type: string): boolean {
+	switch (type) {
+		case "number":
+			return typeof value === "number";
+		case "integer":
+			return typeof value === "number" && Number.isInteger(value);
+		case "boolean":
+			return typeof value === "boolean";
+		case "string":
+			return typeof value === "string";
+		case "null":
+			return value === null;
+		case "array":
+			return Array.isArray(value);
+		case "object":
+			return isRecord(value) && !Array.isArray(value);
+		default:
+			return false;
+	}
+}
+
+function isValidatorSchema(value: unknown): value is Tool["parameters"] {
+	return isRecord(value);
+}
+
+function getSubSchemaValidator(schema: JsonSchemaObject): ReturnType<typeof Compile> | undefined {
+	if (!isValidatorSchema(schema)) {
+		return undefined;
+	}
+	try {
+		return getValidator(schema);
+	} catch {
+		return undefined;
+	}
+}
+
+function coercePrimitiveByType(value: unknown, type: string): unknown {
+	switch (type) {
+		case "number": {
+			if (value === null) {
+				return 0;
+			}
+			if (typeof value === "string" && value.trim() !== "") {
+				const parsed = Number(value);
+				if (Number.isFinite(parsed)) {
+					return parsed;
+				}
+			}
+			if (typeof value === "boolean") {
+				return value ? 1 : 0;
+			}
+			return value;
+		}
+		case "integer": {
+			if (value === null) {
+				return 0;
+			}
+			if (typeof value === "string" && value.trim() !== "") {
+				const parsed = Number(value);
+				if (Number.isInteger(parsed)) {
+					return parsed;
+				}
+			}
+			if (typeof value === "boolean") {
+				return value ? 1 : 0;
+			}
+			return value;
+		}
+		case "boolean": {
+			if (value === null) {
+				return false;
+			}
+			if (typeof value === "string") {
+				if (value === "true") {
+					return true;
+				}
+				if (value === "false") {
+					return false;
+				}
+			}
+			if (typeof value === "number") {
+				if (value === 1) {
+					return true;
+				}
+				if (value === 0) {
+					return false;
+				}
+			}
+			return value;
+		}
+		case "string": {
+			if (value === null) {
+				return "";
+			}
+			if (typeof value === "number" || typeof value === "boolean") {
+				return String(value);
+			}
+			return value;
+		}
+		case "null": {
+			if (value === "" || value === 0 || value === false) {
+				return null;
+			}
+			return value;
+		}
+		default:
+			return value;
+	}
+}
+
+function applySchemaObjectCoercion(value: Record<string, unknown>, schema: JsonSchemaObject): void {
+	const properties = schema.properties;
+	const definedKeys = new Set<string>(properties ? Object.keys(properties) : []);
+
+	if (properties) {
+		for (const [key, propertySchema] of Object.entries(properties)) {
+			if (!(key in value)) {
+				continue;
+			}
+			value[key] = coerceWithJsonSchema(value[key], propertySchema);
+		}
+	}
+
+	if (schema.additionalProperties && isJsonSchemaObject(schema.additionalProperties)) {
+		for (const [key, propertyValue] of Object.entries(value)) {
+			if (definedKeys.has(key)) {
+				continue;
+			}
+			value[key] = coerceWithJsonSchema(propertyValue, schema.additionalProperties);
+		}
+	}
+}
+
+function applySchemaArrayCoercion(value: unknown[], schema: JsonSchemaObject): void {
+	if (Array.isArray(schema.items)) {
+		for (let index = 0; index < value.length; index++) {
+			const itemSchema = schema.items[index];
+			if (!itemSchema) {
+				continue;
+			}
+			value[index] = coerceWithJsonSchema(value[index], itemSchema);
+		}
+		return;
+	}
+
+	if (isJsonSchemaObject(schema.items)) {
+		for (let index = 0; index < value.length; index++) {
+			value[index] = coerceWithJsonSchema(value[index], schema.items);
+		}
+	}
+}
+
+function coerceWithUnionSchema(value: unknown, schemas: JsonSchemaObject[]): unknown {
+	for (const schema of schemas) {
+		const candidate = structuredClone(value);
+		const coerced = coerceWithJsonSchema(candidate, schema);
+		const validator = getSubSchemaValidator(schema);
+		if (validator?.Check(coerced)) {
+			return coerced;
+		}
+	}
+	return value;
+}
+
+function coerceWithJsonSchema(value: unknown, schema: JsonSchemaObject): unknown {
+	let nextValue = value;
+
+	if (Array.isArray(schema.allOf)) {
+		for (const nested of schema.allOf) {
+			nextValue = coerceWithJsonSchema(nextValue, nested);
+		}
+	}
+
+	if (Array.isArray(schema.anyOf)) {
+		nextValue = coerceWithUnionSchema(nextValue, schema.anyOf);
+	}
+
+	if (Array.isArray(schema.oneOf)) {
+		nextValue = coerceWithUnionSchema(nextValue, schema.oneOf);
+	}
+
+	const schemaTypes = getSchemaTypes(schema);
+	const matchesUnionMember =
+		schemaTypes.length > 1 && schemaTypes.some((schemaType) => matchesJsonType(nextValue, schemaType));
+	if (schemaTypes.length > 0 && !matchesUnionMember) {
+		for (const schemaType of schemaTypes) {
+			const candidate = coercePrimitiveByType(nextValue, schemaType);
+			if (candidate !== nextValue) {
+				nextValue = candidate;
+				break;
+			}
+		}
+	}
+
+	if (schemaTypes.includes("object") && isRecord(nextValue) && !Array.isArray(nextValue)) {
+		applySchemaObjectCoercion(nextValue, schema);
+	}
+
+	if (schemaTypes.includes("array") && Array.isArray(nextValue)) {
+		applySchemaArrayCoercion(nextValue, schema);
+	}
+
+	return nextValue;
+}
+
+function getValidator(schema: Tool["parameters"]): ReturnType<typeof Compile> {
+	const key = schema as object;
+	const cached = validatorCache.get(key);
+	if (cached) {
+		return cached;
+	}
+	const validator = Compile(schema);
+	validatorCache.set(key, validator);
+	return validator;
+}
+
+function formatValidationPath(error: TLocalizedValidationError): string {
+	if (error.keyword === "required") {
+		const requiredProperties = (error.params as { requiredProperties?: string[] }).requiredProperties;
+		const requiredProperty = requiredProperties?.[0];
+		if (requiredProperty) {
+			const basePath = error.instancePath.replace(/^\//, "").replace(/\//g, ".");
+			return basePath ? `${basePath}.${requiredProperty}` : requiredProperty;
+		}
+	}
+	const path = error.instancePath.replace(/^\//, "").replace(/\//g, ".");
+	return path || "root";
+}
+
+/**
+ * Finds a tool by name and validates the tool call arguments against its TypeBox schema
+ * @param tools Array of tool definitions
+ * @param toolCall The tool call from the LLM
+ * @returns The validated arguments
+ * @throws Error if tool is not found or validation fails
+ */
+export function validateToolCall(tools: Tool[], toolCall: ToolCall): any {
+	const tool = tools.find((t) => t.name === toolCall.name);
+	if (!tool) {
+		throw new Error(`Tool "${toolCall.name}" not found`);
+	}
+	return validateToolArguments(tool, toolCall);
+}
+
+/**
+ * Validates tool call arguments against the tool's TypeBox schema
+ * @param tool The tool definition with TypeBox schema
+ * @param toolCall The tool call from the LLM
+ * @returns The validated (and potentially coerced) arguments
+ * @throws Error with formatted message if validation fails
+ */
+export function validateToolArguments(tool: Tool, toolCall: ToolCall): any {
+	const args = structuredClone(toolCall.arguments);
+	Value.Convert(tool.parameters, args);
+
+	const validator = getValidator(tool.parameters);
+	if (!hasTypeBoxMetadata(tool.parameters) && isJsonSchemaObject(tool.parameters)) {
+		const coerced = coerceWithJsonSchema(args, tool.parameters);
+		if (coerced !== args) {
+			if (isRecord(args) && isRecord(coerced)) {
+				for (const key of Object.keys(args)) {
+					delete args[key];
+				}
+				Object.assign(args, coerced);
+			} else {
+				return validator.Check(coerced) ? coerced : args;
+			}
+		}
+	}
+
+	if (validator.Check(args)) {
+		return args;
+	}
+
+	const errors =
+		validator
+			.Errors(args)
+			.map((error) => `  - ${formatValidationPath(error)}: ${error.message}`)
+			.join("\n") || "Unknown validation error";
+
+	const errorMessage = `Validation failed for tool "${toolCall.name}":\n${errors}\n\nReceived arguments:\n${JSON.stringify(toolCall.arguments, null, 2)}`;
+
+	throw new Error(errorMessage);
+}