@schlenkr/ragents 0.1.5 → 0.1.6

package/packages/ai/dist/utils/overflow.d.ts

@@ -0,0 +1,54 @@
+import type { AssistantMessage } from "../types.ts";
+/**
+ * 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", "exceeds the model's maximum context length of X tokens", or "exceeds model's maximum context length (X)"
+ * - 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 (most backends): "maximum context length is X tokens"
+ * - OpenRouter/Poolside: "Input length X exceeds the maximum allowed input length of Y tokens."
+ * - Together AI: "The input (X tokens) is longer than the model's context length (Y 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)"
+ * - DS4: "Prompt has X tokens, but the configured context size is Y tokens"
+ *
+ * **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.
+ * - Xiaomi MiMo: Truncates input to fit contextWindow then returns stopReason "length" with
+ *   output=0. Pass contextWindow param to detect via the "filled context + zero output" signal.
+ * - 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 declare function isContextOverflow(message: AssistantMessage, contextWindow?: number): boolean;
+//# sourceMappingURL=overflow.d.ts.map

package/packages/ai/dist/utils/provider-env.d.ts

@@ -0,0 +1,7 @@
+import type { ProviderEnv } from "../types.ts";
+/**
+ * Resolve a provider env value from scoped overrides, normal process.env, then
+ * the duplicated Bun sandbox fallback for direct consumers.
+ */
+export declare function getProviderEnvValue(name: string, env?: ProviderEnv): string | undefined;
+//# sourceMappingURL=provider-env.d.ts.map

package/packages/ai/dist/utils/retry.d.ts

@@ -0,0 +1,12 @@
+import type { AssistantMessage } from "../types.ts";
+/**
+ * Classifies whether a failed assistant message looks like a transient provider
+ * or transport error, so callers can decide if the last assistant turn should be
+ * restarted.
+ *
+ * This does not implement retry policy. Callers should first handle context
+ * overflow separately, then apply their own retry budget, backoff, and reporting
+ * before restarting the assistant turn.
+ */
+export declare function isRetryableAssistantError(message: AssistantMessage): boolean;
+//# sourceMappingURL=retry.d.ts.map

package/packages/ai/dist/utils/sanitize-unicode.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 declare function sanitizeSurrogates(text: string): string;
+//# sourceMappingURL=sanitize-unicode.d.ts.map

package/packages/ai/dist/utils/typebox-helpers.d.ts

@@ -0,0 +1,17 @@
+import { type TUnsafe } 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 declare function StringEnum<T extends readonly string[]>(values: T, options?: {
+    description?: string;
+    default?: T[number];
+}): TUnsafe<T[number]>;
+//# sourceMappingURL=typebox-helpers.d.ts.map

package/packages/ai/dist/utils/validation.d.ts

@@ -0,0 +1,10 @@
+import type { Tool, ToolCall } from "../types.ts";
+/**
+ * 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 declare function validateToolArguments(tool: Tool, toolCall: ToolCall): any;
+//# sourceMappingURL=validation.d.ts.map

package/packages/ai/package.json

@@ -1,7 +1,7 @@
 {
-	"name": "@aicontainer/ai",
+	"name": "@ragents/ai",
 	"version": "0.80.10",
-	"description": "Unified LLM API with automatic model discovery and provider configuration",
+	"description": "The LLM access of RAgents: the OpenRouter provider over AI SDK Core, its model catalog and streaming",
 	"type": "module",
 	"main": "./src/index.ts",
 	"types": "./dist/index.d.ts",
@@ -20,10 +20,6 @@
 		"./api/*": {
 			"types": "./dist/api/*.d.ts",
 			"import": "./src/api/*.ts"
-		},
-		"./oauth": {
-			"types": "./dist/oauth.d.ts",
-			"import": "./src/oauth.ts"
 		}
 	},
 	"scripts": {

package/packages/ai/src/api/ai-sdk-transport.ts

@@ -1,5 +1,5 @@
 import { createOpenRouter } from "@openrouter/ai-sdk-provider";
-import type { ImagesModel, Model, ProviderHeaders } from "../types.ts";
+import type { Model, ProviderHeaders } from "../types.ts";
 import { headersToRecord } from "../utils/headers.ts";
 
 interface SdkOptions<TModel> {
@@ -9,7 +9,7 @@ interface SdkOptions<TModel> {
 	onResponse?: (response: { status: number; headers: Record<string, string> }, model: TModel) => void | Promise<void>;
 }
 
-export function createSdkProvider<TModel extends Model<string> | ImagesModel<string>>(model: TModel, options?: SdkOptions<TModel>) {
+export function createSdkProvider<TModel extends Model<string>>(model: TModel, options?: SdkOptions<TModel>) {
 	const headers = new Headers();
 	const suppressedHeaders = new Set<string>();
 	for (const source of [model.headers, options?.headers]) {

package/packages/ai/src/api/simple-options.ts

@@ -4,8 +4,6 @@ import type {
 	Model,
 	SimpleStreamOptions,
 	StreamOptions,
-	ThinkingBudgets,
-	ThinkingLevel,
 } from "../types.ts";
 import { estimateContextTokens } from "../utils/estimate.ts";
 
@@ -43,35 +41,3 @@ export function buildBaseOptions(
 		env: options?.env,
 	};
 }
-
-export function clampReasoning(effort: ThinkingLevel | undefined): Exclude<ThinkingLevel, "xhigh" | "max"> | undefined {
-	return effort === "xhigh" || effort === "max" ? "high" : effort;
-}
-
-export function adjustMaxTokensForThinking(
-	// Undefined means no explicit caller cap. Use the model cap and fit thinking inside it.
-	baseMaxTokens: number | undefined,
-	modelMaxTokens: number,
-	reasoningLevel: ThinkingLevel,
-	customBudgets?: ThinkingBudgets,
-): { maxTokens: number; thinkingBudget: number } {
-	const defaultBudgets: ThinkingBudgets = {
-		minimal: 1024,
-		low: 2048,
-		medium: 8192,
-		high: 16384,
-	};
-	const budgets = { ...defaultBudgets, ...customBudgets };
-
-	const minOutputTokens = 1024;
-	const level = clampReasoning(reasoningLevel)!;
-	let thinkingBudget = budgets[level]!;
-	const maxTokens =
-		baseMaxTokens === undefined ? modelMaxTokens : Math.min(baseMaxTokens + thinkingBudget, modelMaxTokens);
-
-	if (maxTokens <= thinkingBudget) {
-		thinkingBudget = Math.max(0, maxTokens - minOutputTokens);
-	}
-
-	return { maxTokens, thinkingBudget };
-}

package/packages/ai/src/api-registry.ts

@@ -1,6 +1,5 @@
 import { aiSdkApi } from "./api/ai-sdk.lazy.ts";
 import { getEnvApiKey } from "./env-api-keys.ts";
-import type { ModelsApiStreamOptions } from "./models.ts";
 import { builtinModels } from "./providers/all.ts";
 import { createFauxCore, type FauxProviderRegistration, type RegisterFauxProviderOptions } from "./providers/faux.ts";
 import type {
@@ -90,10 +89,6 @@ export function getApiProvider(api: Api): ApiProviderInternal | undefined {
 	return apiProviderRegistry.get(api)?.provider;
 }
 
-export function getApiProviders(): ApiProviderInternal[] {
-	return Array.from(apiProviderRegistry.values(), (entry) => entry.provider);
-}
-
 export function unregisterApiProviders(sourceId: string): void {
 	for (const [api, entry] of apiProviderRegistry.entries()) {
 		if (entry.sourceId === sourceId) {
@@ -134,12 +129,6 @@ export function registerBuiltInApiProviders(): void {
 	}
 }
 
-export function resetApiProviders(): void {
-	apiProviderRegistry.clear();
-	builtinApiProviderInstances.clear();
-	registerBuiltInApiProviders();
-}
-
 registerBuiltInApiProviders();
 
 const registryModels = builtinModels();
@@ -185,7 +174,7 @@ export function stream<TApi extends Api>(
 	const builtinProvider = getBuiltinProviderForModel(model);
 	if (builtinProvider) {
 		if (model.provider.startsWith("cloudflare-") && !hasResolvedCloudflareAuth(options)) {
-			return registryModels.stream(model, context, options as ModelsApiStreamOptions<TApi> | undefined);
+			return registryModels.stream(model, context, options as ApiStreamOptions<TApi> | undefined);
 		}
 		return builtinProvider.stream(model, context, withEnvApiKey(model, options) as ApiStreamOptions<TApi>);
 	}

package/packages/ai/src/auth/context.ts

@@ -1,45 +1,16 @@
 import type { AuthContext } from "./types.ts";
 
-interface NodeFsModule {
-	access(path: string): Promise<void>;
-}
-
-interface NodeOsModule {
-	homedir(): string;
-}
-
-// Variable specifier so browser bundlers do not try to resolve node builtins.
-const importNodeModule = (specifier: string): Promise<unknown> => import(specifier);
-
 function getProcessEnv(): Record<string, string | undefined> | undefined {
 	const proc = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process;
 	return proc?.env;
 }
 
-/**
- * Default auth context: env vars from `process.env` (undefined in browsers),
- * file existence via node:fs (always false in browsers).
- */
+/** Default auth context: env vars from `process.env` (undefined in browsers). */
 export function defaultProviderAuthContext(): AuthContext {
 	return {
 		async env(name: string): Promise<string | undefined> {
 			const value = getProcessEnv()?.[name];
 			return typeof value === "string" && value.trim().length > 0 ? value : undefined;
 		},
-
-		async fileExists(path: string): Promise<boolean> {
-			try {
-				const fs = (await importNodeModule("node:fs/promises")) as NodeFsModule;
-				let resolved = path;
-				if (resolved.startsWith("~")) {
-					const os = (await importNodeModule("node:os")) as NodeOsModule;
-					resolved = os.homedir() + resolved.slice(1);
-				}
-				await fs.access(resolved);
-				return true;
-			} catch {
-				return false;
-			}
-		},
 	};
 }

package/packages/ai/src/auth/helpers.ts

@@ -1,20 +1,11 @@
-import type { ApiKeyAuth, OAuthAuth } from "./types.ts";
+import type { ApiKeyAuth } from "./types.ts";
 
-/**
- * Standard api-key auth: a stored credential key wins, otherwise the first
- * set env var resolves. Includes a `login` that prompts for the key.
- * Providers with non-standard resolution (provider env, ambient files, IAM)
- * write their own `ApiKeyAuth`.
- */
+/** Standard api-key auth: an explicitly given key wins, otherwise the first set env var resolves. */
 export function envApiKeyAuth(name: string, envVars: readonly string[]): ApiKeyAuth {
 	return {
 		name,
-		login: async (interaction) => {
-			const key = await interaction.prompt({ type: "secret", message: `Enter ${name}` });
-			return { type: "api_key", key };
-		},
 		resolve: async ({ ctx, credential }) => {
-			if (credential?.key) return { auth: { apiKey: credential.key }, source: "stored credential" };
+			if (credential?.key) return { auth: { apiKey: credential.key }, source: "explicit key" };
 			for (const envVar of envVars) {
 				const value = await ctx.env(envVar);
 				if (value) return { auth: { apiKey: value }, source: envVar };
@@ -23,25 +14,3 @@ export function envApiKeyAuth(name: string, envVars: readonly string[]): ApiKeyA
 		},
 	};
 }
-
-/**
- * Wraps a dynamically imported `OAuthAuth` so provider definitions can
- * advertise OAuth without importing the implementation. The flow loads on
- * first `login`/`refresh`/`toAuth` call; callers keep Node-only flow code out
- * of bundles by loading through a bundler-opaque dynamic import (variable
- * specifier, see the bedrock lazy wrapper).
- */
-export function lazyOAuth(input: { name: string; loginLabel?: string; load: () => Promise<OAuthAuth> }): OAuthAuth {
-	let promise: Promise<OAuthAuth> | undefined;
-	const loaded = () => {
-		promise ??= input.load();
-		return promise;
-	};
-	return {
-		name: input.name,
-		loginLabel: input.loginLabel,
-		login: async (interaction) => (await loaded()).login(interaction),
-		refresh: async (credential) => (await loaded()).refresh(credential),
-		toAuth: async (credential) => (await loaded()).toAuth(credential),
-	};
-}

package/packages/ai/src/auth/resolve.ts

@@ -1,17 +1,7 @@
 import type { ProviderEnv } from "../types.ts";
-import type {
-	ApiKeyAuth,
-	ApiKeyCredential,
-	AuthContext,
-	AuthResult,
-	Credential,
-	CredentialStore,
-	OAuthAuth,
-	OAuthCredential,
-	ProviderAuth,
-} from "./types.ts";
+import type { AuthContext, AuthResult, ProviderAuth } from "./types.ts";
 
-export type ModelsErrorCode = "model_source" | "model_validation" | "provider" | "stream" | "auth" | "oauth";
+export type ModelsErrorCode = "provider" | "stream" | "auth";
 
 export interface AuthResolutionOverrides {
 	apiKey?: string;
@@ -28,112 +18,24 @@ export class ModelsError extends Error {
 	}
 }
 
-/**
- * Auth resolution shared by the `Models` and `ImagesModels` collections.
- * A stored credential owns the provider: ambient/env is consulted only when
- * nothing is stored. No silent env fallback after a failed refresh or for a
- * credential type without a matching handler.
- */
+/** Auth resolution of the `Models` collection: an explicit request key wins, otherwise the provider resolves its key. */
 export async function resolveProviderAuth(
 	provider: { id: string; auth: ProviderAuth },
-	credentials: CredentialStore,
 	authContext: AuthContext,
 	overrides?: AuthResolutionOverrides,
 ): Promise<AuthResult | undefined> {
-	const requestAuthContext = overrides?.env ? overlayEnvAuthContext(authContext, overrides.env) : authContext;
-
-	if (overrides?.apiKey !== undefined && provider.auth.apiKey) {
-		return resolveApiKey(requestAuthContext, provider.auth.apiKey, provider.id, {
-			type: "api_key",
-			key: overrides.apiKey,
-			env: overrides.env,
-		});
-	}
-
-	const stored = await readCredential(credentials, provider.id);
-	if (stored) {
-		if (stored.type === "oauth" && provider.auth.oauth) {
-			return resolveStoredOAuth(credentials, provider.id, provider.auth.oauth, stored);
-		}
-		if (stored.type === "api_key" && provider.auth.apiKey) {
-			const credential = overrides?.env ? { ...stored, env: { ...stored.env, ...overrides.env } } : stored;
-			return resolveApiKey(requestAuthContext, provider.auth.apiKey, provider.id, credential);
-		}
-		return undefined;
+	const ctx = overrides?.env ? overlayEnvAuthContext(authContext, overrides.env) : authContext;
+	const credential =
+		overrides?.apiKey !== undefined ? { type: "api_key" as const, key: overrides.apiKey, env: overrides.env } : undefined;
+	try {
+		return await provider.auth.apiKey.resolve({ ctx, credential });
+	} catch (error) {
+		throw new ModelsError("auth", `API key auth failed for provider ${provider.id}`, { cause: error });
 	}
-
-	// Ambient (env vars, AWS profiles, ADC files).
-	return provider.auth.apiKey
-		? resolveApiKey(requestAuthContext, provider.auth.apiKey, provider.id, undefined)
-		: undefined;
 }
 
 function overlayEnvAuthContext(base: AuthContext, env: ProviderEnv): AuthContext {
 	return {
 		env: async (name) => env[name] || (await base.env(name)),
-		fileExists: (path) => base.fileExists(path),
 	};
 }
-
-/**
- * OAuth resolution with double-checked locking (same pattern as today's
- * AuthStorage): valid tokens cost zero locks; expired tokens lock, re-check
- * expiry under the lock, refresh once globally, and persist the rotated
- * credential before release.
- */
-async function resolveStoredOAuth(
-	credentials: CredentialStore,
-	providerId: string,
-	oauth: OAuthAuth,
-	stored: OAuthCredential,
-): Promise<AuthResult | undefined> {
-	let credential = stored;
-
-	if (Date.now() >= credential.expires) {
-		// Optimistic check said expired; the authoritative check runs under the lock.
-		let post: Credential | undefined;
-		try {
-			post = await credentials.modify(providerId, async (current) => {
-				if (current?.type !== "oauth") return undefined; // logged out meanwhile
-				if (Date.now() < current.expires) return undefined; // another process/request refreshed
-				try {
-					return await oauth.refresh(current);
-				} catch (error) {
-					throw new ModelsError("oauth", `OAuth refresh failed for ${providerId}`, { cause: error });
-				}
-			});
-		} catch (error) {
-			if (error instanceof ModelsError) throw error;
-			throw new ModelsError("auth", `Credential store modify failed for ${providerId}`, { cause: error });
-		}
-		if (post?.type !== "oauth") return undefined; // logged out meanwhile
-		credential = post;
-	}
-
-	try {
-		return { auth: await oauth.toAuth(credential), source: "OAuth" };
-	} catch (error) {
-		throw new ModelsError("oauth", `OAuth auth derivation failed for ${providerId}`, { cause: error });
-	}
-}
-
-async function resolveApiKey(
-	authContext: AuthContext,
-	apiKey: ApiKeyAuth,
-	providerId: string,
-	credential: ApiKeyCredential | undefined,
-): Promise<AuthResult | undefined> {
-	try {
-		return await apiKey.resolve({ ctx: authContext, credential });
-	} catch (error) {
-		throw new ModelsError("auth", `API key auth failed for provider ${providerId}`, { cause: error });
-	}
-}
-
-async function readCredential(credentials: CredentialStore, providerId: string): Promise<Credential | undefined> {
-	try {
-		return await credentials.read(providerId);
-	} catch (error) {
-		throw new ModelsError("auth", `Credential store read failed for ${providerId}`, { cause: error });
-	}
-}