@librechat/agents 3.1.56 → 3.1.60

package/dist/types/utils/errors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Context overflow error detection utilities.
+ *
+ * Identifies provider-specific error messages that indicate the request
+ * exceeded the model's context window. Used by the overflow recovery loop
+ * to decide whether to retry with truncation/compaction vs. propagating
+ * the error.
+ */
+/**
+ * Extracts a human-readable error message from an unknown error value.
+ */
+export declare function extractErrorMessage(error: unknown): string;
+/**
+ * Returns true if the error message definitively indicates a context
+ * overflow / prompt-too-large error from the provider.
+ *
+ * This is the strict check: only matches known, unambiguous phrases.
+ * Use this when you want high confidence before taking recovery action.
+ */
+export declare function isContextOverflowError(errorMessage?: string): boolean;
+/**
+ * Returns true if the error message likely indicates a context overflow.
+ * Uses broader heuristic matching (regex) in addition to exact phrases.
+ *
+ * May produce false positives for unusual error messages. Use this when
+ * the cost of a false positive (one extra retry) is acceptable.
+ */
+export declare function isLikelyContextOverflowError(errorMessage?: string): boolean;

package/dist/types/utils/events.d.ts

@@ -1,6 +1,19 @@
 import type { RunnableConfig } from '@langchain/core/runnables';
+import type { AgentLogEvent } from '@/types/graph';
 /**
  * Safely dispatches a custom event and properly awaits it to avoid
  * race conditions where events are dispatched after run cleanup.
  */
 export declare function safeDispatchCustomEvent(event: string, payload: unknown, config?: RunnableConfig): Promise<void>;
+/**
+ * Fire-and-forget diagnostic log event.
+ * Debug-level logs are gated behind AGENT_DEBUG_LOGGING=true to avoid
+ * overhead in production. Info/warn/error always flow through.
+ * Pass `force: true` to bypass the env-var gate (e.g. invoke timing).
+ */
+export declare function emitAgentLog(config: RunnableConfig | undefined, level: AgentLogEvent['level'], scope: AgentLogEvent['scope'], message: string, data?: Record<string, unknown>, meta?: {
+    runId?: string;
+    agentId?: string;
+}, options?: {
+    force?: boolean;
+}): void;

package/dist/types/utils/index.d.ts

@@ -5,3 +5,5 @@ export * from './handlers';
 export * from './run';
 export * from './tokens';
 export * from './schema';
+export * from './truncation';
+export * from './errors';

package/dist/types/utils/llm.d.ts

@@ -1,3 +1,7 @@
 import { Providers } from '@/common';
 export declare function isOpenAILike(provider?: string | Providers): boolean;
 export declare function isGoogleLike(provider?: string | Providers): boolean;
+/** Returns true for native Anthropic or Bedrock running a Claude model. */
+export declare function isAnthropicLike(provider?: string | Providers, clientOptions?: {
+    model?: string;
+}): boolean;

package/dist/types/utils/tokens.d.ts

@@ -1,7 +1,20 @@
 import type { BaseMessage } from '@langchain/core/messages';
 export type EncodingName = 'o200k_base' | 'claude';
+/**
+ * Extracts image dimensions from the first bytes of a base64-encoded
+ * PNG, JPEG, GIF, or WebP without decoding the full image.
+ * Returns null if the format is unrecognized or data is too short.
+ */
+export declare function extractImageDimensions(base64Data: string): {
+    width: number;
+    height: number;
+} | null;
+/** Estimates image token cost for Anthropic/Bedrock (Claude). */
+export declare function estimateAnthropicImageTokens(width: number, height: number): number;
+/** Estimates image token cost for OpenAI (high detail). */
+export declare function estimateOpenAIImageTokens(width: number, height: number, detail?: string): number;
 export declare function encodingForModel(model: string): EncodingName;
-export declare function getTokenCountForMessage(message: BaseMessage, getTokenCount: (text: string) => number): number;
+export declare function getTokenCountForMessage(message: BaseMessage, getTokenCount: (text: string) => number, encoding?: EncodingName): number;
 /**
  * Creates a token counter function using the specified encoding.
  * Lazily loads the encoding data on first use via dynamic import.

package/dist/types/utils/truncation.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Ingestion-time and pre-flight truncation utilities for tool results.
+ *
+ * Prevents oversized tool outputs from entering the message array and
+ * consuming the entire context window.
+ */
+/**
+ * Absolute hard cap on tool result length (characters).
+ * Even if the model has a 1M-token context, a single tool result
+ * larger than this is almost certainly a bug (e.g., dumping a binary file).
+ */
+export declare const HARD_MAX_TOOL_RESULT_CHARS = 400000;
+/**
+ * Computes the dynamic max tool result size based on the model's context window.
+ * Uses 30% of the context window (in estimated characters, ~4 chars/token)
+ * capped at HARD_MAX_TOOL_RESULT_CHARS.
+ *
+ * @param contextWindowTokens - The model's max context tokens (optional).
+ * @returns Maximum allowed characters for a single tool result.
+ */
+export declare function calculateMaxToolResultChars(contextWindowTokens?: number): number;
+/**
+ * Truncates a tool-call input (the arguments/payload of a tool_use block)
+ * using head+tail strategy. Returns an object with `_truncated` (the
+ * truncated string) and `_originalChars` (for diagnostics).
+ *
+ * Accepts any type — objects are JSON-serialized before truncation.
+ *
+ * @param input - The tool input (string, object, etc.).
+ * @param maxChars - Maximum allowed characters.
+ */
+export declare function truncateToolInput(input: unknown, maxChars: number): {
+    _truncated: string;
+    _originalChars: number;
+};
+/**
+ * Truncates tool result content that exceeds `maxChars` using a head+tail
+ * strategy. Keeps the beginning (structure/headers) and end (return value /
+ * conclusion) of the content so the model retains both the opening context
+ * and the final outcome.
+ *
+ * Head gets ~70% of the budget, tail gets ~30%. Falls back to head-only
+ * when the budget is too small for a meaningful tail.
+ *
+ * @param content - The tool result string content.
+ * @param maxChars - Maximum allowed characters.
+ * @returns The (possibly truncated) content string.
+ */
+export declare function truncateToolResultContent(content: string, maxChars: number): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.1.56",
+  "version": "3.1.60",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -112,7 +112,7 @@
     "@browserbasehq/stagehand": {
       "openai": "$openai"
     },
-    "fast-xml-parser": "5.3.8",
+    "fast-xml-parser": "5.5.6",
     "ajv": "6.14.0",
     "minimatch": "3.1.4"
   },